perf(storybook): improve deployed build performance

[egdev6]

Summary

• Removes the deployed Storybook startup request for ../src/styles/global.css while keeping the runtime preview CSS import.
• Restores Storybook build treeshaking and hashed asset output so generated assets can be cached safely.
• Adds Netlify cache headers and a repeatable Storybook build-size report command.

Closes #273

Review scope

• Primary files/areas: Storybook build config, Storybook head post-processing, Netlify headers, build reporting script.
• Out of scope: removing/gating Storybook addons, rewriting component stories, changing component runtime code.
• Review workload: small; focused infra/config/script diff.

Type of change

• New component
• Existing component update/refactor
• Bug fix
• Accessibility
• Design tokens
• Storybook/docs
• Infrastructure/tooling
• NPM/dependencies

Workflow gates

• Linked issue is present with Closes #NNN or maintainer approved an exception.
• Linked issue has label status:approved before implementation starts.
• Linked issue assignee was checked before work started; if it was assigned to someone else, explicit reassignment permission is documented.
• Work was started through the Project flow: assignee set, Project status In progress, branch/worktree recorded.
• PR title follows Conventional Commit format: <type>(<optional scope>): <description>.
• Commits follow the same commitlint-enforced format.
• Diff is focused; unrelated work is called out in Review scope.
• MCP/runtime artifacts are absent: .playwright-mcp, page-*.png, page-*.jpeg, *.md.playwright-output.

Component evidence (required for component changes)

• Validated component spec is linked or quoted in the issue.
• Accessibility contract from the spec was implemented or deviations are explained below.
• Follows the 6-file pattern: types.ts, use*.ts, Component.tsx, Component.test.tsx, Component.stories.tsx, index.ts.
• CVA variants live in types.ts; JSX component has no state, CVA calls, or business logic.
• Public props with runtime defaults have matching @default JSDoc in types.ts (node scripts/verify-prop-default-docs.mjs).
• Uses design tokens from theme.css; no hardcoded colors or arbitrary color utilities.
• Storybook covers default, variants, documented states, edge cases, and dark mode when visually different.
• Component audit result is PASS or accepted PASS WITH WARNINGS.
• Visual review result is included when visuals changed.

N/A — no component runtime changes.

Accessibility evidence

• Role/name semantics verified with Testing Library queries or equivalent.
• Keyboard-only behavior verified: Tab / Shift+Tab, Enter / Space, Arrow keys, Escape, Home / End / typeahead where applicable.
• Focus lifecycle verified: initial focus, roving/active descendant, focus restore, trap/portal behavior where applicable.
• Disabled, required, invalid/error, loading, and empty states expose the expected semantics where applicable.
• Reduced motion behavior is respected where motion changed.
• Screen reader or axe/manual evidence is included below when applicable.

N/A — no component behavior or accessibility contract changed. Storybook a11y addon remains enabled.

Validation evidence

• TypeScript: pnpm exec tsc --noEmit ✅
• Unit tests: pnpm test via pre-push hook ✅ — 35 files / 745 tests passed
• Build/package: pnpm run storybook-build ✅
• Storybook or visual check:
  • pnpm run storybook-report ✅
  • No built/head-fragment ../src/styles/global.css reference ✅
  • Preview CSS import remains in .storybook/preview.tsx ✅
  • Baseline raw JS: 9,449,330 bytes / 1856 files
  • Updated raw JS: 8,917,497 bytes / 1847 files (-531,833, -5.63%)
• Accessibility check: Storybook a11y addon preserved; no component a11y behavior changed.
• Security/dependency check: N/A — no dependency or lockfile changes.

Screenshots or recordings

N/A — config/build change. Deploy smoke check should verify headers and network requests on the Netlify preview.

Notes for reviewer

• Netlify headers still need verification on the deployed preview for /, /index.html, /iframe.html, and one hashed /assets/* file.
• Heavy addons intentionally remain in scope-preserving mode; further addon gating can be handled in a follow-up if desired.
• Maintainer approval to proceed was captured in the working session before implementation; GitHub status:approved, assignee, and Project In progress were updated before opening this PR.

[Copilot]

Pull request overview

This PR improves deployed Storybook performance by removing a broken deploy-only CSS request, re-enabling more cache-friendly Storybook build outputs, and adding deployment/build reporting tooling to track regressions.

Changes:

• Remove the deploy-time ../src/styles/global.css link from Storybook’s preview-head.html while keeping the runtime CSS import in preview.
• Restore more cacheable Storybook build output (hashed assets) and remove the explicit Rollup treeshaking disable.
• Add Netlify cache headers for HTML vs. immutable hashed assets, plus a CLI script to report Storybook build size.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/report-storybook-build.mjs	Adds a repeatable build-size reporting script (total size, JS count/bytes, top assets).
scripts/inject-preview-head.js	Updates post-build head normalization messaging for index.html / iframe.html.
package.json	Adds storybook-report script entry.
netlify.toml	Adds cache headers: revalidate HTML, long-cache immutable /assets/*.
.storybook/preview-head.html	Removes deploy-only broken CSS <link> request.
.storybook/main.ts	Restores hashed asset naming and removes explicit treeshake: false.
.gitattributes	Extends whitespace attribute checks to *.js, *.mjs, and *.json.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.