prizmkit 1.1.54 → 1.1.55

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

@@ -0,0 +1,320 @@
+# Frontend Rules — {{ project_name }}
+
+> This document was generated by the `frontend-rules` skill on {{ generated_at }}
+> Scope: {{ project_scope }}
+> Design/mockup source: {{ 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
+
+---
+
+## 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
+
+- 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`)
+
+### 1.3 Dark Mode
+
+{{ dark_mode_rules }}
+
+### 1.4 Responsive Breakpoints
+
+{{ breakpoint_rules }}
+
+### 1.5 Style Deny List
+
+{{ FIXED_RULES_DENY_LIST }}
+
+---
+
+## 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
+
+{{ FIXED_RULES_COMPONENT_CONTRACT }}
+
+### 2.2 Tech Stack Lock-in
+
+{{ 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.
+
+---
+
+## 3. Code Quality (Non-Negotiable)
+
+### 3.1 Type Safety
+
+{{ 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
+
+### 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
+
+---
+
+## 4. State & Data
+
+### 4.1 Global State ({{ state_lib }})
+
+{{ state_rules }}
+
+### 4.2 Server State ({{ server_state_lib }})
+
+{{ server_state_rules }}
+
+### 4.3 API Types
+
+- 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>`
+
+### 4.4 Forms
+
+- 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
+
+---
+
+## 5. User Experience
+
+### 5.1 Four-State UI (Mandatory)
+
+Any view containing async operations must explicitly handle:
+
+- **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.
+
+### 5.2 Error Handling Rules
+
+{{ FIXED_RULES_ERROR_HANDLING }}
+
+### 5.3 Accessibility (Target: {{ a11y_level }})
+
+{{ FIXED_RULES_A11Y }}
+
+{{ a11y_extra_rules }}
+
+### 5.4 Internationalization
+
+{{ FIXED_RULES_I18N_BASELINE }}
+
+{{ i18n_rules }}
+
+### 5.5 Performance Baseline
+
+{{ 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
+
+{{ test_rules }}
+
+### 6.2 Coverage Thresholds
+
+- Shared components: ≥ 80%
+- Business modules: ≥ 60%
+- Critical flows (login, payment, checkout, etc.): E2E coverage mandatory
+
+---
+
+## 7. AI Vibecoding Behavior Constraints
+
+### 7.1 Baseline Constraints (project-agnostic, always active)
+
+{{ 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
+
+### 7.3 Project-Specific Hard Constraints
+
+- **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 }}
+
+### 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
+
+{{ FIXED_RULES_GIT }}
+
+### 8.2 Code Review Checklist
+
+PR submitter must self-check the following:
+
+- [ ] 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
+
+{{ 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.
+
+{{ deny_list_summary }}
+
+## Appendix B: Recommended Libraries & Tools
+
+> 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.
+
+{{ 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/`
+
+---
+
+**Version**: v1.0 — Generated on {{ generated_at }}
+**Next review recommended**: at project milestones or tech stack changes