Establish theme v2 governance and migration rules for GameFoundryStudio - PR_26152_021-theme-v2-css-governance

Author: ToolboxAid

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -145,6 +145,57 @@ Use that phrase as a compact IA and copywriting anchor:
 - Play: playable games, arcade browsing, testing, saves, and discovery.
 - Share: marketplace assets, tutorials, community visibility, publishing, and creator identity.
 
+## GAMEFOUNDRYSTUDIO THEME V2 GOVERNANCE
+
+`theme/v2` is the only approved styling surface for new GameFoundryStudio work.
+
+Existing CSS is deprecated and compatibility-only.
+
+Rules:
+- Do not extend deprecated CSS.
+- Do not create new CSS files outside `theme/v2`.
+- No page-local CSS.
+- No tool-local CSS.
+- No inline style attributes.
+- No `<style>` blocks.
+- No JavaScript-generated styling except toggling approved `theme/v2` classes.
+- No hardcoded colors.
+- No hardcoded spacing.
+- No hardcoded borders.
+- No hardcoded shadows.
+- No hardcoded font sizes.
+- No hardcoded z-index values.
+- No duplicate component styling.
+- No copy/paste of deprecated selectors into `theme/v2`.
+- No one-off classes for a single page or tool unless approved and promoted into `theme/v2`.
+- New UI work must first attempt to use existing `theme/v2` tokens and classes.
+- Missing styling requirements must be reported as design-system gaps.
+- Design-system gaps should be documented rather than solved locally.
+
+Allowed:
+- Adding reusable `theme/v2` tokens.
+- Adding reusable `theme/v2` component classes.
+- Toggling approved `theme/v2` classes from JavaScript.
+- Removing deprecated CSS.
+- Consolidating duplicate CSS into `theme/v2`.
+
+Exception documentation is required for any approved deviation and must include:
+- File.
+- Reason.
+- Follow-up plan.
+
+Migration order:
+1. Home
+2. Company pages
+3. Admin pages
+4. Account pages
+5. Tools index
+6. Tool families
+7. Games
+8. Samples
+
+Do not migrate pages during governance-only PRs unless the PR explicitly authorizes migration work.
+
 ## FILE SCOPE GUARD
 
 Allowed change scope is PR-specific.

docs/dev/reports/theme_v2_governance_validation.md

@@ -0,0 +1,45 @@
+# Theme V2 Governance Validation
+
+Task: PR_26152_021-theme-v2-css-governance
+
+Scope:
+- Governance documentation only.
+- No GameFoundryStudio page migration.
+- No runtime, CSS, HTML, or JavaScript behavior changes.
+
+Changed files:
+- `docs/dev/PROJECT_INSTRUCTIONS.md`
+- `docs/dev/reports/theme_v2_governance_validation.md`
+- `docs/dev/reports/codex_changed_files.txt`
+- `docs/dev/reports/codex_review.diff`
+- `docs/dev/commit_comment.txt`
+
+Validation performed:
+- Ran `git diff --check -- docs/dev/PROJECT_INSTRUCTIONS.md`.
+  - Result: Passed.
+  - Note: Git reported a line-ending normalization warning only.
+- Ran targeted documentation validation for `docs/dev/PROJECT_INSTRUCTIONS.md`.
+  - Verified the Theme V2 Governance section exists exactly once.
+  - Verified `theme/v2` is documented as the only approved styling surface for new GameFoundryStudio work.
+  - Verified deprecated CSS is documented as compatibility-only.
+  - Verified no page-local CSS and no tool-local CSS rules exist.
+  - Verified inline style, `<style>` block, JavaScript-generated styling, hardcoded values, duplicate styling, and deprecated selector copy/paste restrictions exist.
+  - Verified allowed Theme V2 token, component, class toggling, deprecated CSS removal, and consolidation guidance exists.
+  - Verified exception documentation requires file, reason, and follow-up plan.
+  - Verified migration order exists:
+    1. Home
+    2. Company pages
+    3. Admin pages
+    4. Account pages
+    5. Tools index
+    6. Tool families
+    7. Games
+    8. Samples
+
+Explicitly not run:
+- No repo-wide tests.
+- No tests outside GameFoundryStudio.
+- No full samples smoke test.
+- No runtime tests because this PR is governance-only documentation.
+
+Result: Passed.