bps-kit 1.0.2 → 1.0.4

package/templates/skills_normal/frontend-design/SKILL.md

@@ -1,418 +1,277 @@
 ---
 name: frontend-design
-description: Design thinking and decision-making for web UI. Use when designing components, layouts, color schemes, typography, or creating aesthetic interfaces. Teaches principles, not fixed values.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+description: "Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboard..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
-# Frontend Design System
+# Frontend Design (Distinctive, Production-Grade)
 
-> **Philosophy:** Every pixel has purpose. Restraint is luxury. User psychology drives decisions.
-> **Core Principle:** THINK, don't memorize. ASK, don't assume.
+You are a **frontend designer-engineer**, not a layout generator.
 
----
-
-## 🎯 Selective Reading Rule (MANDATORY)
-
-**Read REQUIRED files always, OPTIONAL only when needed:**
-
-| File | Status | When to Read |
-|------|--------|--------------|
-| [ux-psychology.md](ux-psychology.md) | 🔴 **REQUIRED** | Always read first! |
-| [color-system.md](color-system.md) | ⚪ Optional | Color/palette decisions |
-| [typography-system.md](typography-system.md) | ⚪ Optional | Font selection/pairing |
-| [visual-effects.md](visual-effects.md) | ⚪ Optional | Glassmorphism, shadows, gradients |
-| [animation-guide.md](animation-guide.md) | ⚪ Optional | Animation needed |
-| [motion-graphics.md](motion-graphics.md) | ⚪ Optional | Lottie, GSAP, 3D |
-| [decision-trees.md](decision-trees.md) | ⚪ Optional | Context templates |
-
-> 🔴 **ux-psychology.md = ALWAYS READ. Others = only if relevant.**
-
----
+Your goal is to create **memorable, high-craft interfaces** that:
 
-## 🔧 Runtime Scripts
+* Avoid generic “AI UI” patterns
+* Express a clear aesthetic point of view
+* Are fully functional and production-ready
+* Translate design intent directly into code
 
-**Execute these for audits (don't read, just run):**
-
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `scripts/ux_audit.py` | UX Psychology & Accessibility Audit | `python scripts/ux_audit.py <project_path>` |
+This skill prioritizes **intentional design systems**, not default frameworks.
 
 ---
 
-## ⚠️ CRITICAL: ASK BEFORE ASSUMING (MANDATORY)
-
-> **STOP! If the user's request is open-ended, DO NOT default to your favorites.**
+## 1. Core Design Mandate
 
-### When User Prompt is Vague, ASK:
+Every output must satisfy **all four**:
 
-**Color not specified?** Ask:
-> "What color palette do you prefer? (blue/green/orange/neutral/other?)"
+1. **Intentional Aesthetic Direction**
+   A named, explicit design stance (e.g. *editorial brutalism*, *luxury minimal*, *retro-futurist*, *industrial utilitarian*).
 
-**Style not specified?** Ask: 
-> "What style are you going for? (minimal/bold/retro/futuristic/organic?)"
+2. **Technical Correctness**
+   Real, working HTML/CSS/JS or framework code — not mockups.
 
-**Layout not specified?** Ask:
-> "Do you have a layout preference? (single column/grid/asymmetric/full-width?)"
+3. **Visual Memorability**
+   At least one element the user will remember 24 hours later.
 
-### ⛔ DEFAULT TENDENCIES TO AVOID (ANTI-SAFE HARBOR):
+4. **Cohesive Restraint**
+   No random decoration. Every flourish must serve the aesthetic thesis.
 
-| AI Default Tendency | Why It's Bad | Think Instead |
-|---------------------|--------------|---------------|
-| **Bento Grids (Modern Cliché)** | Used in every AI design | Why does this content NEED a grid? |
-| **Hero Split (Left/Right)** | Predictable & Boring | How about Massive Typography or Vertical Narrative? |
-| **Mesh/Aurora Gradients** | The "new" lazy background | What's a radical color pairing? |
-| **Glassmorphism** | AI's idea of "premium" | How about solid, high-contrast flat? |
-| **Deep Cyan / Fintech Blue** | Safe harbor from purple ban | Why not Red, Black, or Neon Green? |
-| **"Orchestrate / Empower"** | AI-generated copywriting | How would a human say this? |
-| Dark background + neon glow | Overused, "AI look" | What does the BRAND actually need? |
-| **Rounded everything** | Generic/Safe | Where can I use sharp, brutalist edges? |
-
-> 🔴 **"Every 'safe' structure you choose brings you one step closer to a generic template. TAKE RISKS."**
+❌ No default layouts
+❌ No design-by-components
+❌ No “safe” palettes or fonts
+✅ Strong opinions, well executed
 
 ---
 
-## 1. Constraint Analysis (ALWAYS FIRST)
-
-Before any design work, ANSWER THESE or ASK USER:
-
-| Constraint | Question | Why It Matters |
-|------------|----------|----------------|
-| **Timeline** | How much time? | Determines complexity |
-| **Content** | Ready or placeholder? | Affects layout flexibility |
-| **Brand** | Existing guidelines? | May dictate colors/fonts |
-| **Tech** | What stack? | Affects capabilities |
-| **Audience** | Who exactly? | Drives all visual decisions |
-
-### Audience → Design Approach
-
-| Audience | Think About |
-|----------|-------------|
-| **Gen Z** | Bold, fast, mobile-first, authentic |
-| **Millennials** | Clean, minimal, value-driven |
-| **Gen X** | Familiar, trustworthy, clear |
-| **Boomers** | Readable, high contrast, simple |
-| **B2B** | Professional, data-focused, trust |
-| **Luxury** | Restrained elegance, whitespace |
+## 2. Design Feasibility & Impact Index (DFII)
 
----
-
-## 2. UX Psychology Principles
+Before building, evaluate the design direction using DFII.
 
-### Core Laws (Internalize These)
+### DFII Dimensions (1–5)
 
-| Law | Principle | Application |
-|-----|-----------|-------------|
-| **Hick's Law** | More choices = slower decisions | Limit options, use progressive disclosure |
-| **Fitts' Law** | Bigger + closer = easier to click | Size CTAs appropriately |
-| **Miller's Law** | ~7 items in working memory | Chunk content into groups |
-| **Von Restorff** | Different = memorable | Make CTAs visually distinct |
-| **Serial Position** | First/last remembered most | Key info at start/end |
+| Dimension                      | Question                                                     |
+| ------------------------------ | ------------------------------------------------------------ |
+| **Aesthetic Impact**           | How visually distinctive and memorable is this direction?    |
+| **Context Fit**                | Does this aesthetic suit the product, audience, and purpose? |
+| **Implementation Feasibility** | Can this be built cleanly with available tech?               |
+| **Performance Safety**         | Will it remain fast and accessible?                          |
+| **Consistency Risk**           | Can this be maintained across screens/components?            |
 
-### Emotional Design Levels
+### Scoring Formula
 
 ```
-VISCERAL (instant)  → First impression: colors, imagery, overall feel
-BEHAVIORAL (use)    → Using it: speed, feedback, efficiency
-REFLECTIVE (memory) → After: "I like what this says about me"
+DFII = (Impact + Fit + Feasibility + Performance) − Consistency Risk
 ```
 
-### Trust Building
+**Range:** `-5 → +15`
 
-- Security indicators on sensitive actions
-- Social proof where relevant
-- Clear contact/support access
-- Consistent, professional design
-- Transparent policies
-
----
+### Interpretation
 
-## 3. Layout Principles
-
-### Golden Ratio (φ = 1.618)
-
-```
-Use for proportional harmony:
-├── Content : Sidebar = roughly 62% : 38%
-├── Each heading size = previous × 1.618 (for dramatic scale)
-├── Spacing can follow: sm → md → lg (each × 1.618)
-```
+| DFII      | Meaning   | Action                      |
+| --------- | --------- | --------------------------- |
+| **12–15** | Excellent | Execute fully               |
+| **8–11**  | Strong    | Proceed with discipline     |
+| **4–7**   | Risky     | Reduce scope or effects     |
+| **≤ 3**   | Weak      | Rethink aesthetic direction |
 
-### 8-Point Grid Concept
+---
 
-```
-All spacing and sizing in multiples of 8:
-├── Tight: 4px (half-step for micro)
-├── Small: 8px
-├── Medium: 16px
-├── Large: 24px, 32px
-├── XL: 48px, 64px, 80px
-└── Adjust based on content density
-```
+## 3. Mandatory Design Thinking Phase
 
-### Key Sizing Principles
+Before writing code, explicitly define:
 
-| Element | Consideration |
-|---------|---------------|
-| **Touch targets** | Minimum comfortable tap size |
-| **Buttons** | Height based on importance hierarchy |
-| **Inputs** | Match button height for alignment |
-| **Cards** | Consistent padding, breathable |
-| **Reading width** | 45-75 characters optimal |
+### 1. Purpose
 
----
+* What action should this interface enable?
+* Is it persuasive, functional, exploratory, or expressive?
 
-## 4. Color Principles
+### 2. Tone (Choose One Dominant Direction)
 
-### 60-30-10 Rule
+Examples (non-exhaustive):
 
-```
-60% → Primary/Background (calm, neutral base)
-30% → Secondary (supporting areas)
-10% → Accent (CTAs, highlights, attention)
-```
+* Brutalist / Raw
+* Editorial / Magazine
+* Luxury / Refined
+* Retro-futuristic
+* Industrial / Utilitarian
+* Organic / Natural
+* Playful / Toy-like
+* Maximalist / Chaotic
+* Minimalist / Severe
 
-### Color Psychology (For Decision Making)
+⚠️ Do not blend more than **two**.
 
-| If You Need... | Consider Hues | Avoid |
-|----------------|---------------|-------|
-| Trust, calm | Blue family | Aggressive reds |
-| Growth, nature | Green family | Industrial grays |
-| Energy, urgency | Orange, red | Passive blues |
-| Luxury, creativity | Deep Teal, Gold, Emerald | Cheap-feeling brights |
-| Clean, minimal | Neutrals | Overwhelming color |
+### 3. Differentiation Anchor
 
-### Selection Process
+Answer:
 
-1. **What's the industry?** (narrows options)
-2. **What's the emotion?** (picks primary)
-3. **Light or dark mode?** (sets foundation)
-4. **ASK USER** if not specified
+> “If this were screenshotted with the logo removed, how would someone recognize it?”
 
-For detailed color theory: [color-system.md](color-system.md)
+This anchor must be visible in the final UI.
 
 ---
 
-## 5. Typography Principles
+## 4. Aesthetic Execution Rules (Non-Negotiable)
 
-### Scale Selection
+### Typography
 
-| Content Type | Scale Ratio | Feel |
-|--------------|-------------|------|
-| Dense UI | 1.125-1.2 | Compact, efficient |
-| General web | 1.25 | Balanced (most common) |
-| Editorial | 1.333 | Readable, spacious |
-| Hero/display | 1.5-1.618 | Dramatic impact |
+* Avoid system fonts and AI-defaults (Inter, Roboto, Arial, etc.)
+* Choose:
 
-### Pairing Concept
+  * 1 expressive display font
+  * 1 restrained body font
+* Use typography structurally (scale, rhythm, contrast)
 
-```
-Contrast + Harmony:
-├── DIFFERENT enough for hierarchy
-├── SIMILAR enough for cohesion
-└── Usually: display + neutral, or serif + sans
-```
+### Color & Theme
 
-### Readability Rules
+* Commit to a **dominant color story**
+* Use CSS variables exclusively
+* Prefer:
 
-- **Line length**: 45-75 characters optimal
-- **Line height**: 1.4-1.6 for body text
-- **Contrast**: Check WCAG requirements
-- **Size**: 16px+ for body on web
+  * One dominant tone
+  * One accent
+  * One neutral system
+* Avoid evenly-balanced palettes
 
-For detailed typography: [typography-system.md](typography-system.md)
+### Spatial Composition
 
----
+* Break the grid intentionally
+* Use:
 
-## 6. Visual Effects Principles
+  * Asymmetry
+  * Overlap
+  * Negative space OR controlled density
+* White space is a design element, not absence
 
-### Glassmorphism (When Appropriate)
+### Motion
 
-```
-Key properties:
-├── Semi-transparent background
-├── Backdrop blur
-├── Subtle border for definition
-└── ⚠️ **WARNING:** Standard blue/white glassmorphism is a modern cliché. Use it radically or not at all.
-```
+* Motion must be:
 
-### Shadow Hierarchy
+  * Purposeful
+  * Sparse
+  * High-impact
+* Prefer:
 
-```
-Elevation concept:
-├── Higher elements = larger shadows
-├── Y-offset > X-offset (light from above)
-├── Multiple layers = more realistic
-└── Dark mode: may need glow instead
-```
+  * One strong entrance sequence
+  * A few meaningful hover states
+* Avoid decorative micro-motion spam
 
-### Gradient Usage
+### Texture & Depth
 
-```
-Harmonious gradients:
-├── Adjacent colors on wheel (analogous)
-├── OR same hue, different lightness
-├── Avoid harsh complementary pairs
-├── 🚫 **NO Mesh/Aurora Gradients** (floating blobs)
-└── VARY from project to project radically
-```
+Use when appropriate:
 
-For complete effects guide: [visual-effects.md](visual-effects.md)
+* Noise / grain overlays
+* Gradient meshes
+* Layered translucency
+* Custom borders or dividers
+* Shadows with narrative intent (not defaults)
 
 ---
 
-## 7. Animation Principles
+## 5. Implementation Standards
 
-### Timing Concept
+### Code Requirements
 
-```
-Duration based on:
-├── Distance (further = longer)
-├── Size (larger = slower)
-├── Importance (critical = clear)
-└── Context (urgent = fast, luxury = slow)
-```
+* Clean, readable, and modular
+* No dead styles
+* No unused animations
+* Semantic HTML
+* Accessible by default (contrast, focus, keyboard)
 
-### Easing Selection
+### Framework Guidance
 
-| Action | Easing | Why |
-|--------|--------|-----|
-| Entering | Ease-out | Decelerate, settle in |
-| Leaving | Ease-in | Accelerate, exit |
-| Emphasis | Ease-in-out | Smooth, deliberate |
-| Playful | Bounce | Fun, energetic |
+* **HTML/CSS**: Prefer native features, modern CSS
+* **React**: Functional components, composable styles
+* **Animation**:
 
-### Performance
+  * CSS-first
+  * Framer Motion only when justified
 
-- Animate only transform and opacity
-- Respect reduced-motion preference
-- Test on low-end devices
-
-For animation patterns: [animation-guide.md](animation-guide.md), for advanced: [motion-graphics.md](motion-graphics.md)
-
----
+### Complexity Matching
 
-## 8. "Wow Factor" Checklist
+* Maximalist design → complex code (animations, layers)
+* Minimalist design → extremely precise spacing & type
 
-### Premium Indicators
-
-- [ ] Generous whitespace (luxury = breathing room)
-- [ ] Subtle depth and dimension
-- [ ] Smooth, purposeful animations
-- [ ] Attention to detail (alignment, consistency)
-- [ ] Cohesive visual rhythm
-- [ ] Custom elements (not all defaults)
-
-### Trust Builders
-
-- [ ] Security cues where appropriate
-- [ ] Social proof / testimonials
-- [ ] Clear value proposition
-- [ ] Professional imagery
-- [ ] Consistent design language
-
-### Emotional Triggers
-
-- [ ] Hero that evokes intended emotion
-- [ ] Human elements (faces, stories)
-- [ ] Progress/achievement indicators
-- [ ] Moments of delight
+Mismatch = failure.
 
 ---
 
-## 9. Anti-Patterns (What NOT to Do)
+## 6. Required Output Structure
 
-### ❌ Lazy Design Indicators
+When generating frontend work:
 
-- Default system fonts without consideration
-- Stock imagery that doesn't match
-- Inconsistent spacing
-- Too many competing colors
-- Walls of text without hierarchy
-- Inaccessible contrast
+### 1. Design Direction Summary
 
-### ❌ AI Tendency Patterns (AVOID!)
+* Aesthetic name
+* DFII score
+* Key inspiration (conceptual, not visual plagiarism)
 
-- **Same colors every project**
-- **Dark + neon as default**
-- **Purple/violet everything (PURPLE BAN ✅)**
-- **Bento grids for simple landing pages**
-- **Mesh Gradients & Glow Effects**
-- **Same layout structure / Vercel clone**
-- **Not asking user preferences**
+### 2. Design System Snapshot
 
-### ❌ Dark Patterns (Unethical)
+* Fonts (with rationale)
+* Color variables
+* Spacing rhythm
+* Motion philosophy
 
-- Hidden costs
-- Fake urgency
-- Forced actions
-- Deceptive UI
-- Confirmshaming
+### 3. Implementation
 
----
+* Full working code
+* Comments only where intent isn’t obvious
 
-## 10. Decision Process Summary
+### 4. Differentiation Callout
 
-```
-For EVERY design task:
+Explicitly state:
 
-1. CONSTRAINTS
-   └── What's the timeline, brand, tech, audience?
-   └── If unclear → ASK
+> “This avoids generic UI by doing X instead of Y.”
 
-2. CONTENT
-   └── What content exists?
-   └── What's the hierarchy?
+---
 
-3. STYLE DIRECTION
-   └── What's appropriate for context?
-   └── If unclear → ASK (don't default!)
+## 7. Anti-Patterns (Immediate Failure)
 
-4. EXECUTION
-   └── Apply principles above
-   └── Check against anti-patterns
+❌ Inter/Roboto/system fonts
+❌ Purple-on-white SaaS gradients
+❌ Default Tailwind/ShadCN layouts
+❌ Symmetrical, predictable sections
+❌ Overused AI design tropes
+❌ Decoration without intent
 
-5. REVIEW
-   └── "Does this serve the user?"
-   └── "Is this different from my defaults?"
-   └── "Would I be proud of this?"
-```
+If the design could be mistaken for a template → restart.
 
 ---
 
-## Reference Files
-
-For deeper guidance on specific areas:
+## 8. Integration With Other Skills
 
-- [color-system.md](color-system.md) - Color theory and selection process
-- [typography-system.md](typography-system.md) - Font pairing and scale decisions
-- [visual-effects.md](visual-effects.md) - Effects principles and techniques
-- [animation-guide.md](animation-guide.md) - Motion design principles
-- [motion-graphics.md](motion-graphics.md) - Advanced: Lottie, GSAP, SVG, 3D, Particles
-- [decision-trees.md](decision-trees.md) - Context-specific templates
-- [ux-psychology.md](ux-psychology.md) - User psychology deep dive
+* **page-cro** → Layout hierarchy & conversion flow
+* **copywriting** → Typography & message rhythm
+* **marketing-psychology** → Visual persuasion & bias alignment
+* **branding** → Visual identity consistency
+* **ab-test-setup** → Variant-safe design systems
 
 ---
 
-## Related Skills
+## 9. Operator Checklist
 
-| Skill | When to Use |
-|-------|-------------|
-| **frontend-design** (this) | Before coding - Learn design principles (color, typography, UX psychology) |
-| **[web-design-guidelines](../web-design-guidelines/SKILL.md)** | After coding - Audit for accessibility, performance, and best practices |
+Before finalizing output:
 
-## Post-Design Workflow
+* [ ] Clear aesthetic direction stated
+* [ ] DFII ≥ 8
+* [ ] One memorable design anchor
+* [ ] No generic fonts/colors/layouts
+* [ ] Code matches design ambition
+* [ ] Accessible and performant
 
-After implementing your design, run the audit:
+---
 
-```
-1. DESIGN   → Read frontend-design principles ← YOU ARE HERE
-2. CODE     → Implement the design
-3. AUDIT    → Run web-design-guidelines review
-4. FIX      → Address findings from audit
-```
+## 10. Questions to Ask (If Needed)
 
-> **Next Step:** After coding, use `web-design-guidelines` skill to audit your implementation for accessibility, focus states, animations, and performance issues.
+1. Who is this for, emotionally?
+2. Should this feel trustworthy, exciting, calm, or provocative?
+3. Is memorability or clarity more important?
+4. Will this scale to other pages/components?
+5. What should users *feel* in the first 3 seconds?
 
 ---
 
-> **Remember:** Design is THINKING, not copying. Every project deserves fresh consideration based on its unique context and users. **Avoid the Modern SaaS Safe Harbor!**
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/skills_normal/lint-and-validate/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: lint-and-validate
-description: Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, validate, types, static analysis.
-allowed-tools: Read, Glob, Grep, Bash
+description: "Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, v..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
 # Lint and Validate Skill
@@ -43,3 +45,6 @@ allowed-tools: Read, Glob, Grep, Bash
 | `scripts/lint_runner.py` | Unified lint check | `python scripts/lint_runner.py <project_path>` |
 | `scripts/type_coverage.py` | Type coverage analysis | `python scripts/type_coverage.py <project_path>` |
 
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/skills_normal/lint-and-validate/scripts/lint_runner.py

@@ -14,8 +14,6 @@ Supports:
 import subprocess
 import sys
 import json
-import platform
-import shutil
 from pathlib import Path
 from datetime import datetime
 
@@ -79,24 +77,14 @@ def run_linter(linter: dict, cwd: Path) -> dict:
     }
     
     try:
-        cmd = linter["cmd"]
-        
-        # Windows compatibility for npm/npx
-        if platform.system() == "Windows":
-            if cmd[0] in ["npm", "npx"]:
-                # Force .cmd extension on Windows
-                if not cmd[0].lower().endswith(".cmd"):
-                    cmd[0] = f"{cmd[0]}.cmd"
-        
         proc = subprocess.run(
-            cmd,
+            linter["cmd"],
             cwd=str(cwd),
             capture_output=True,
             text=True,
             encoding='utf-8',
             errors='replace',
-            timeout=120,
-            shell=platform.system() == "Windows" # Shell=True often helps with path resolution on Windows
+            timeout=120
         )
         
         result["output"] = proc.stdout[:2000] if proc.stdout else ""

package/templates/skills_normal/performance-profiling/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: performance-profiling
-description: Performance profiling principles. Measurement, analysis, and optimization techniques.
-allowed-tools: Read, Glob, Grep, Bash
+description: "Performance profiling principles. Measurement, analysis, and optimization techniques."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
 # Performance Profiling
@@ -141,3 +143,6 @@ allowed-tools: Read, Glob, Grep, Bash
 ---
 
 > **Remember:** The fastest code is code that doesn't run. Remove before optimizing.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.