prizmkit 1.1.154 → 1.1.156

package/bundled/skills/app-planner/references/rules/frontend/template.md

@@ -1,339 +1,161 @@
 # Frontend Rules — {{ project_name }}
 
-> This document was generated by the `frontend-rules` skill on {{ generated_at }}
+> Generated by app-planner Rules Configuration
 > Scope: {{ project_scope }}
 > Design basis: {{ design_source }}
-> Audience: All human developers + all AI coding assistants on this project
->
-> **Usage**:
-> 1. All AI coding assistants must read this file before generating or modifying any frontend code
-> 2. This document takes precedence over "general best practices" in AI training data
-> 3. Code conflicting with this document must not be committed
-> 4. Modifying this document requires team review
-
----
-
-## Table of Contents
-
-- [0. TL;DR — Key Decisions at a Glance](#0-tldr--key-decisions-at-a-glance)
-- [1. Design System](#1-design-system)
-- [2. Engineering Architecture](#2-engineering-architecture)
-- [3. Code Quality (Non-Negotiable)](#3-code-quality-non-negotiable)
-- [4. State & Data](#4-state--data)
-- [5. User Experience](#5-user-experience)
-- [6. Testing & Quality Assurance](#6-testing--quality-assurance)
-- [7. AI Vibecoding Behavior Constraints](#7-ai-vibecoding-behavior-constraints)
-- [8. Collaboration Process](#8-collaboration-process)
-- [9. Security Baseline](#9-security-baseline)
-- [Appendix A: Deny List (Quick Reference)](#appendix-a-deny-list-quick-reference)
-- [Appendix B: Recommended Libraries & Tools](#appendix-b-recommended-libraries--tools)
-- [Appendix C: References](#appendix-c-references)
-
----
-
-
-## 0. TL;DR — Key Decisions at a Glance
-
-| Dimension | Decision |
-|-----------|----------|
-| Framework | {{ framework }} |
-| Meta-Framework | {{ meta_framework }} |
-| Package Manager | {{ package_manager }} |
-| Styling Solution | {{ style_solution }} |
-| Font Strategy | {{ font_strategy }} |
-| Global State | {{ state_lib }} |
-| Server State | {{ server_state_lib }} |
-| API Type Source | {{ api_type_source }} |
-| Design Token Layers | {{ token_layering }} |
-| Dark Mode | {{ dark_mode }} |
-| Responsive Strategy | {{ responsive_strategy }} |
-| Breakpoints | {{ breakpoint_scheme }} |
-| Internationalization | {{ i18n }} |
-| Accessibility Target | {{ a11y_level }} |
-| Test Coverage | {{ test_coverage }} |
-| Unit Test Framework | {{ unit_test_framework }} |
-| E2E Framework | {{ e2e_framework }} |
-| AI Single File Limit | {{ ai_max_lines }} lines |
-| First Screen LCP Target | {{ lcp_target }} |
-| Single Chunk Limit | {{ bundle_size }} |
-
----
-
-## 1. Design System
-
-### 1.1 Design Token Layers
-
-{{ token_layering_rules }}
-
-### 1.2 Naming Conventions
+> Audience: project contributors and AI coding assistants working in the declared scope
 
-- Colors: `color.{role}.{variant}` (e.g., `color.brand.primary`, `color.text.muted`)
-- Spacing: `space.{step}` (e.g., `space.4` = 16px)
-- Font sizes: `font.size.{role}` (e.g., `font.size.body`)
-- Border radius: `radius.{step}` (e.g., `radius.md`)
-- Shadows: `shadow.{level}` (e.g., `shadow.elevated`)
+This document is generated from confirmed decisions. A recommendation is non-binding unless it appears in the decision ledger or an active rule block.
 
-### 1.3 Dark Mode
+## 1. Decision Ledger
 
-{{ dark_mode_rules }}
-
-### 1.4 Responsive Breakpoints
-
-{{ breakpoint_rules }}
-
-### 1.5 Style Deny List
-
-{{ FIXED_RULES_DENY_LIST }}
+| Domain | Selected Decision |
+|---|---|
+| Framework | {{ framework }} |
+| Meta-framework | {{ meta_framework }} |
+| Package manager | {{ package_manager }} |
+| Styling | {{ style_solution }} |
+| Font strategy | {{ font_strategy }} |
+| Global state | {{ state_lib }} |
+| Server state | {{ server_state_lib }} |
+| API type source | {{ api_type_source }} |
+| Token layering | {{ token_layering }} |
+| Dark mode | {{ dark_mode }} |
+| Responsive strategy | {{ responsive_strategy }} |
+| Breakpoints | {{ breakpoint_scheme }} |
+| Localization | {{ i18n }} |
+| Accessibility | {{ a11y_level }} |
+| Test depth | {{ test_coverage }} |
+| Unit test framework | {{ unit_test_framework }} |
+| E2E framework | {{ e2e_framework }} |
+| File-size guidance | {{ ai_max_lines }} |
+| LCP target | {{ lcp_target }} |
+| Bundle target | {{ bundle_size }} |
 
----
-
-## 2. Engineering Architecture
-
-### 2.1 Directory Structure (Mandatory)
-
-```
-src/
-├── app/              # Routes/page entry points
-├── components/       # Shared components (must export to components/index.ts)
-│   └── index.ts      # Component index (AI must read this before deciding to create a new component)
-├── features/         # Business modules (organized by domain)
-│   └── <domain>/
-│       ├── api/
-│       ├── components/
-│       ├── hooks/
-│       └── index.ts
-├── hooks/            # Shared hooks
-├── lib/              # Third-party wrappers, utilities
-├── stores/           # Global state
-├── styles/           # Global styles + tokens
-├── types/            # Global types
-└── utils/            # Pure function utilities
-```
-
-#### Component Contract
+If a decision is deferred or not applicable, its cell and section state that explicitly.
 
-{{ FIXED_RULES_COMPONENT_CONTRACT }}
+## 2. Stack and Architecture
 
-### 2.2 Tech Stack Lock-in
+### 2.1 Selected stack
 
 {{ tech_stack_rules }}
 
-**New dependencies must undergo team review** — AI must not modify `package.json` to introduce new packages on its own.
-
-### 2.3 Styling Solution Specific Rules
-
-{{ style_specific_rules }}
-
-### 2.4 Routing Conventions
-
-> Routing rules come from the official conventions of `{{ meta_framework }}`, already incorporated in §2.2 Tech Stack Lock-in.
-> Additional project rules: Route file naming follows meta-framework default conventions. Forbid custom route matchers unless there is an explicit architectural decision.
+### 2.2 Component contract
 
----
-
-## 3. Code Quality (Non-Negotiable)
+{{ FIXED_RULES_COMPONENT_CONTRACT }}
 
-### 3.1 Type Safety
+### 2.3 Type and naming integrity
 
 {{ FIXED_RULES_TYPESCRIPT }}
 
-### 3.2 Naming Conventions
-
 {{ FIXED_RULES_NAMING }}
 
-### 3.3 File & Component Size
-
-- Single file ≤ {{ ai_max_lines }} lines (including blank lines and comments)
-- Single function ≤ 50 lines
-- Single component props ≤ 8 (beyond this, consider splitting or using object aggregation)
-- Nesting depth ≤ 4 levels
+### 2.4 Styling
 
-### 3.4 ESLint / Prettier
-
-- Config files must be committed to the repository
-- Pre-commit hooks enforce lint and format
-- Forbid file-level `eslint-disable`. Exceptions require documented reasons and review
+{{ FIXED_RULES_DENY_LIST }}
 
----
+{{ style_specific_rules }}
 
-## 4. State & Data
+### 2.5 Design tokens and themes
 
-### 4.1 Global State ({{ state_lib }})
+{{ token_layering_rules }}
 
-{{ state_rules }}
+{{ dark_mode_rules }}
 
-### 4.2 Server State ({{ server_state_lib }})
+### 2.6 Responsive behavior
 
-{{ server_state_rules }}
+{{ breakpoint_rules }}
 
-### 4.3 API Types
+## 3. State, Data, and Forms
 
-- API type source: {{ api_type_source }}
-- Forbid hand-writing types related to backend contracts (unless API type source is "hand-written .d.ts")
-- All request functions must return fully-typed Promises. Forbid `Promise<any>`
+### 3.1 Global state
 
-### 4.4 Forms
+{{ state_rules }}
 
-- Form state management follows the best practices of the chosen state library ({{ state_lib }})
-- Client-side + server-side validation dual protection. Forbid relying solely on client-side validation
-- Error messages must be displayed inline near the corresponding field and support keyboard focus
-- Submit buttons must have a loading state to prevent duplicate submissions
+### 3.2 Server state and API contracts
 
----
+{{ server_state_rules }}
 
-## 5. User Experience
+- Selected API type source: {{ api_type_source }}
+- Preserve the selected type-source boundary; generated, shared, and hand-written sources must not be mixed without an explicit migration.
 
-### 5.1 Four-State UI (Mandatory)
+### 3.3 Forms
 
-Any view containing async operations must explicitly handle:
+- Use the project's selected form pattern when one exists; the global-state choice does not automatically become the form library.
+- Validate on both the usability boundary and the authoritative server boundary where applicable.
+- Prevent duplicate non-idempotent submissions and keep field errors accessible.
 
-- **loading**: skeleton screen / spinner. Forbid white screen.
-- **error**: error message + retry button. Forbid just `console.error`.
-- **empty**: empty state illustration + guided action.
-- **success**: normal rendering.
+## 4. User Experience and Safety
 
-### 5.2 Error Handling Rules
+### 4.1 Error and async-state handling
 
 {{ FIXED_RULES_ERROR_HANDLING }}
 
-### 5.3 Accessibility (Target: {{ a11y_level }})
+### 4.2 Accessibility
 
 {{ FIXED_RULES_A11Y }}
 
 {{ a11y_extra_rules }}
 
-### 5.4 Internationalization
+### 4.3 Localization
 
 {{ FIXED_RULES_I18N_BASELINE }}
 
 {{ i18n_rules }}
 
-### 5.5 Performance Baseline
+### 4.4 Performance
 
 {{ FIXED_RULES_PERFORMANCE }}
 
 {{ performance_rules }}
 
-### 5.6 Animation
-
-- All animations must be ≤ 300ms (page transitions excepted)
-- Must respect `prefers-reduced-motion`
-- Forbid using animation properties that block the main thread (like `top` / `left` — use `transform` instead)
-
----
-
-## 6. Testing & Quality Assurance
-
-### 6.1 Testing Strategy
+## 5. Testing
 
 {{ test_rules }}
 
-### 6.2 Coverage Thresholds
-
-- Shared components: ≥ 80%
-- Business modules: ≥ 60%
-- Critical flows (login, payment, checkout, etc.): E2E coverage mandatory
+Only thresholds and test tiers stated by the selected testing decision are mandatory. Deferred testing is recorded as accepted risk rather than replaced by hidden defaults.
 
----
+## 6. AI Change Permissions
 
-## 7. AI Vibecoding Behavior Constraints
-
-### 7.1 Baseline Constraints (project-agnostic, always active)
+### 6.1 Invariant change safety
 
 {{ FIXED_RULES_AI_BASE }}
 
-### 7.2 Mandatory Pre-Actions (before every code generation)
-
-AI must complete the following in order before generating or modifying any frontend code:
-
-1. Read this file (`frontend-rules.md`)
-2. Read `src/components/index.ts` to confirm whether a reusable component already exists
-3. Read the target module's `README.md` or `index.ts` (if present)
-4. If modifying a shared component, search all callers and list the impact
+### 6.2 Selected permissions
 
-### 7.3 Project-Specific Hard Constraints
+- Dependency changes: {{ ai_dependency_rule }}
+- Shared component impact analysis: {{ ai_breaking_change_rule }}
+- Configuration changes: {{ ai_config_rule }}
+- Component index synchronization: {{ ai_index_rule }}
+- File-size guidance: {{ ai_max_lines }}
 
-- **Single file line limit**: {{ ai_max_lines }} lines
-- **Adding dependencies**: {{ ai_dependency_rule }}
-- **Modifying shared components**: {{ ai_breaking_change_rule }}
-- **New component registration trifecta**: ① Register in `components/index.ts` ② Add example in preview page ③ Export props types
-- **Config file modification**: {{ ai_config_rule }}
-- **New component index sync**: {{ ai_index_rule }}
+Selected permissions own these domains. No fixed or appendix rule may silently narrow or broaden them.
 
-### 7.4 Forbidden Behaviors
-
-- ❌ Self-initiated `npm install` to introduce new dependencies
-- ❌ Modifying `package.json`, `tsconfig.json`, `vite.config.*`, `next.config.*`, ESLint/Prettier config (unless explicitly requested by user)
-- ❌ Deleting or renaming exported APIs (unless explicitly requested by user with caller impact assessed)
-- ❌ Skipping type definitions (writing `any` / `as any` / `// @ts-ignore`)
-- ❌ Introducing hardcoded colors/font sizes/spacing that bypass design tokens
-- ❌ "Incidental changes" spanning more than 5 files in a single commit
-- ❌ Creating a new component without reading `components/index.ts` first
-
-### 7.5 Output Format Convention
-
-After completing code generation, AI must output:
-
-1. **Change list**: files added / modified / deleted
-2. **Impact**: modified exported APIs and their callers
-3. **Not done**: items mentioned in the user's original request but not addressed this time
-4. **Next steps**: up to 3 suggestions
-
----
-
-## 8. Collaboration Process
-
-### 8.1 Branching & Commits
+## 7. Collaboration
 
 {{ FIXED_RULES_GIT }}
 
-### 8.2 Code Review Checklist
-
-PR submitter must self-check the following:
+Review against the selected decisions, affected public contracts, applicable states, accessibility, security, and the selected testing evidence. Do not enforce a technology or process that the decision ledger did not select.
 
-- [ ] Follows this spec (no `any`, no `!important`, no hardcoded values)
-- [ ] Reuses existing components from `components/index.ts`
-- [ ] Has loading / error / empty states
-- [ ] Has accessibility handling (label, aria, keyboard)
-- [ ] Has i18n (no hardcoded user-visible text)
-- [ ] Has unit tests (shared components) / E2E (critical flows)
-- [ ] Single file ≤ {{ ai_max_lines }} lines
-- [ ] New dependencies added? If so, has it been submitted for review?
-- [ ] Shared components modified? If so, has the impact been listed?
-
-### 8.3 Best Practices for AI Collaboration
-
-- Task granularity: let AI do one thing at a time. Avoid "while you're at it, also add xxx"
-- Verification granularity: run locally once after every AI output before merging
-- Dispute handling: when AI output conflicts with this spec, **this spec takes precedence**
-
----
-
-## 9. Security Baseline
+## 8. Security
 
 {{ FIXED_RULES_SECURITY }}
 
----
-
-## Appendix A: Deny List (Quick Reference)
-
-> This appendix is auto-generated by AI in Phase 4 by extracting key forbidden entries from §1.5 (Style Deny List), §3 (Code Quality), §7.4 (AI Forbidden Behaviors), and §9 (Security Baseline) to provide a one-glance review.
+## Appendix A: Active Deny List
 
 {{ deny_list_summary }}
 
-## Appendix B: Recommended Libraries & Tools
+The deny list is derived only from active invariant and selected rule blocks; it must not include rejected or not-applicable options.
 
-> This appendix is auto-generated by AI in Phase 4 based on the chosen tech stack ({{ framework }} / {{ style_solution }} / {{ state_lib }} etc.) to recommend the supporting ecosystem.
+## Appendix B: Compatible Recommendations
 
 {{ recommended_libs }}
 
-## Appendix C: References
-
-- This document was generated by the `frontend-rules` skill
-- To modify this document, invoke the `frontend-rules` skill and choose "Incremental update" mode
-- Original rule library: `.claude/skills/frontend-rules/references/`
+Recommendations must be compatible with the selected stack and dependency-permission rule. They are not authorization to modify dependencies.
 
----
+## Source Contract
 
-**Version**: v1.0 — Generated on {{ generated_at }}
-**Next review recommended**: at project milestones or tech stack changes
+- Owner: app-planner Rules Configuration
+- Resource family: `references/rules/frontend/`
+- Regenerate after changing a selected decision or source contract; do not patch contradictory generated sections independently.
+- Generation metadata value: {{ generated_at }}