@mohammadhprp/system-prompt 0.11.1 → 0.12.0

package/framework/skills/taste/references/stitch-design-taste.md

@@ -0,0 +1,179 @@
+# Stitch Design Taste — Semantic Design System Skill
+
+## Overview
+This skill generates `DESIGN.md` files optimized for Google Stitch screen generation. It translates the battle-tested anti-slop frontend engineering directives into Stitch's native semantic design language — descriptive, natural-language rules paired with precise values that Stitch's AI agent can interpret to produce premium, non-generic interfaces.
+
+The generated `DESIGN.md` serves as the **single source of truth** for prompting Stitch to generate new screens that align with a curated, high-agency design language. Stitch interprets design through **"Visual Descriptions"** supported by specific color values, typography specs, and component behaviors.
+
+## Prerequisites
+- Access to Google Stitch via [labs.google/stitch](https://labs.google/stitch)
+- Optionally: Stitch MCP Server for programmatic integration with Cursor, Antigravity, or Gemini CLI
+
+## The Goal
+Generate a `DESIGN.md` file that encodes:
+1. **Visual atmosphere** — the mood, density, and design philosophy
+2. **Color calibration** — neutrals, accents, and banned patterns with hex codes
+3. **Typographic architecture** — font stacks, scale hierarchy, and anti-patterns
+4. **Component behaviors** — buttons, cards, inputs with interaction states
+5. **Layout principles** — grid systems, spacing philosophy, responsive strategy
+6. **Motion philosophy** — animation engine specs, spring physics, perpetual micro-interactions
+7. **Anti-patterns** — explicit list of banned AI design clichés
+
+## Analysis & Synthesis Instructions
+
+### 1. Define the Atmosphere
+Evaluate the target project's intent. Use evocative adjectives from the taste spectrum:
+- **Density:** "Art Gallery Airy" (1–3) → "Daily App Balanced" (4–7) → "Cockpit Dense" (8–10)
+- **Variance:** "Predictable Symmetric" (1–3) → "Offset Asymmetric" (4–7) → "Artsy Chaotic" (8–10)
+- **Motion:** "Static Restrained" (1–3) → "Fluid CSS" (4–7) → "Cinematic Choreography" (8–10)
+
+Default baseline: Variance 8, Motion 6, Density 4. Adapt dynamically based on user's vibe description.
+
+### 2. Map the Color Palette
+For each color provide: **Descriptive Name** + **Hex Code** + **Functional Role**.
+
+**Mandatory constraints:**
+- Maximum 1 accent color. Saturation below 80%
+- The "AI Purple/Blue Neon" aesthetic is strictly BANNED — no purple button glows, no neon gradients
+- Use absolute neutral bases (Zinc/Slate) with high-contrast singular accents
+- Stick to one palette for the entire output — no warm/cool gray fluctuation
+- Never use pure black (`#000000`) — use Off-Black, Zinc-950, or Charcoal
+
+### 3. Establish Typography Rules
+- **Display/Headlines:** Track-tight, controlled scale. Not screaming. Hierarchy through weight and color, not just massive size
+- **Body:** Relaxed leading, max 65 characters per line
+- **Font Selection:** `Inter` is BANNED for premium/creative contexts. Force unique character: `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`
+- **Serif Ban:** Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) are BANNED. If serif is needed for editorial/creative contexts, use only distinctive modern serifs: `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Serif is always BANNED in dashboards or software UIs
+- **Dashboard Constraint:** Use Sans-Serif pairings exclusively (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`)
+- **High-Density Override:** When density exceeds 7, all numbers must use Monospace
+
+### 4. Define the Hero Section
+The Hero is the first impression and must be creative, striking, and never generic:
+- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Images sit inline at type-height, rounded, acting as visual punctuation. This is the signature creative technique
+- **No Overlapping:** Text must never overlap images or other text. Every element occupies its own clean spatial zone
+- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons are BANNED. The content should pull users in naturally
+- **Asymmetric Structure:** Centered Hero layouts BANNED when variance exceeds 4
+- **CTA Restraint:** Maximum one primary CTA. No secondary "Learn more" links
+
+### 5. Describe Component Stylings
+For each component type, describe shape, color, shadow depth, and interaction behavior:
+- **Buttons:** Tactile push feedback on active state. No neon outer glows. No custom mouse cursors
+- **Cards:** Use ONLY when elevation communicates hierarchy. Tint shadows to background hue. For high-density layouts, replace cards with border-top dividers or negative space
+- **Inputs/Forms:** Label above input, helper text optional, error text below. Standard gap spacing
+- **Loading States:** Skeletal loaders matching layout dimensions — no generic circular spinners
+- **Empty States:** Composed compositions indicating how to populate data
+- **Error States:** Clear, inline error reporting
+
+### 6. Define Layout Principles
+- No overlapping elements — every element occupies its own clear spatial zone. No absolute-positioned content stacking
+- Centered Hero sections are BANNED when variance exceeds 4 — force Split Screen, Left-Aligned, or Asymmetric Whitespace
+- The generic "3 equal cards horizontally" feature row is BANNED — use 2-column Zig-Zag, asymmetric grid, or horizontal scroll
+- CSS Grid over Flexbox math — never use `calc()` percentage hacks
+- Contain layouts using max-width constraints (e.g., 1400px centered)
+- Full-height sections must use `min-h-[100dvh]` — never `h-screen` (iOS Safari catastrophic jump)
+
+### 7. Define Responsive Rules
+Every design must work across all viewports:
+- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to single column. No exceptions
+- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure
+- **Typography Scaling:** Headlines scale via `clamp()`. Body text minimum `1rem`/`14px`
+- **Touch Targets:** All interactive elements minimum `44px` tap target
+- **Image Behavior:** Inline typography images (photos between words) stack below headline on mobile
+- **Navigation:** Desktop horizontal nav collapses to clean mobile menu
+- **Spacing:** Vertical section gaps reduce proportionally (`clamp(3rem, 8vw, 6rem)`)
+
+### 8. Encode Motion Philosophy
+- **Spring Physics default:** `stiffness: 100, damping: 20` — premium, weighty feel. No linear easing
+- **Perpetual Micro-Interactions:** Every active component should have an infinite loop state (Pulse, Typewriter, Float, Shimmer)
+- **Staggered Orchestration:** Never mount lists instantly — use cascade delays for waterfall reveals
+- **Performance:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`. Grain/noise filters on fixed pseudo-elements only
+
+### 9. List Anti-Patterns (AI Tells)
+Encode these as explicit "NEVER DO" rules in the DESIGN.md:
+- No emojis anywhere
+- No `Inter` font
+- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — distinctive modern serifs only if needed
+- No pure black (`#000000`)
+- No neon/outer glow shadows
+- No oversaturated accents
+- No excessive gradient text on large headers
+- No custom mouse cursors
+- No overlapping elements — clean spatial separation always
+- No 3-column equal card layouts
+- No generic names ("John Doe", "Acme", "Nexus")
+- No fake round numbers (`99.99%`, `50%`)
+- No AI copywriting clichés ("Elevate", "Seamless", "Unleash", "Next-Gen")
+- No filler UI text: "Scroll to explore", "Swipe down", scroll arrows, bouncing chevrons
+- No broken Unsplash links — use `picsum.photos` or SVG avatars
+- No centered Hero sections (for high-variance projects)
+
+## Output Format (DESIGN.md Structure)
+
+```markdown
+# Design System: [Project Title]
+
+## 1. Visual Theme & Atmosphere
+(Evocative description of the mood, density, variance, and motion intensity.
+Example: "A restrained, gallery-airy interface with confident asymmetric layouts
+and fluid spring-physics motion. The atmosphere is clinical yet warm — like a
+well-lit architecture studio.")
+
+## 2. Color Palette & Roles
+- **Canvas White** (#F9FAFB) — Primary background surface
+- **Pure Surface** (#FFFFFF) — Card and container fill
+- **Charcoal Ink** (#18181B) — Primary text, Zinc-950 depth
+- **Muted Steel** (#71717A) — Secondary text, descriptions, metadata
+- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, 1px structural lines
+- **[Accent Name]** (#XXXXXX) — Single accent for CTAs, active states, focus rings
+(Max 1 accent. Saturation < 80%. No purple/neon.)
+
+## 3. Typography Rules
+- **Display:** [Font Name] — Track-tight, controlled scale, weight-driven hierarchy
+- **Body:** [Font Name] — Relaxed leading, 65ch max-width, neutral secondary color
+- **Mono:** [Font Name] — For code, metadata, timestamps, high-density numbers
+- **Banned:** Inter, generic system fonts for premium contexts. Serif fonts banned in dashboards.
+
+## 4. Component Stylings
+* **Buttons:** Flat, no outer glow. Tactile -1px translate on active. Accent fill for primary, ghost/outline for secondary.
+* **Cards:** Generously rounded corners (2.5rem). Diffused whisper shadow. Used only when elevation serves hierarchy. High-density: replace with border-top dividers.
+* **Inputs:** Label above, error below. Focus ring in accent color. No floating labels.
+* **Loaders:** Skeletal shimmer matching exact layout dimensions. No circular spinners.
+* **Empty States:** Composed, illustrated compositions — not just "No data" text.
+
+## 5. Layout Principles
+(Grid-first responsive architecture. Asymmetric splits for Hero sections.
+Strict single-column collapse below 768px. Max-width containment.
+No flexbox percentage math. Generous internal padding.)
+
+## 6. Motion & Interaction
+(Spring physics for all interactive elements. Staggered cascade reveals.
+Perpetual micro-loops on active dashboard components. Hardware-accelerated
+transforms only. Isolated Client Components for CPU-heavy animations.)
+
+## 7. Anti-Patterns (Banned)
+(Explicit list of forbidden patterns: no emojis, no Inter, no pure black,
+no neon glows, no 3-column equal grids, no AI copywriting clichés,
+no generic placeholder names, no broken image links.)
+```
+
+## Best Practices
+- **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
+- **Be Functional:** Explain what each element is used for
+- **Be Consistent:** Same terminology throughout the document
+- **Be Precise:** Include exact hex codes, rem values, pixel values in parentheses
+- **Be Opinionated:** This is not a neutral template — it enforces a specific, premium aesthetic
+
+## Tips for Success
+1. Start with the atmosphere — understand the vibe before detailing tokens
+2. Look for patterns — identify consistent spacing, sizing, and styling
+3. Think semantically — name colors by purpose, not just appearance
+4. Consider hierarchy — document how visual weight communicates importance
+5. Encode the bans — anti-patterns are as important as the rules themselves
+
+## Common Pitfalls to Avoid
+- Using technical jargon without translation ("rounded-xl" instead of "generously rounded corners")
+- Omitting hex codes or using only descriptive names
+- Forgetting functional roles of design elements
+- Being too vague in atmosphere descriptions
+- Ignoring the anti-pattern list — these are what make the output premium
+- Defaulting to generic "safe" designs instead of enforcing the curated aesthetic

package/framework/skills/technical-design-doc-creator/README.md

@@ -0,0 +1,411 @@
+# Technical Design Doc Creator
+
+A skill for AI coding agents that helps create comprehensive Technical Design Documents (TDDs) following industry standards.
+
+## What It Does
+
+This skill guides AI agents to create well-structured Technical Design Documents that include:
+
+- **Mandatory sections**: Context, Problem Statement, Scope, Technical Solution, Risks, Implementation Plan
+- **Critical sections**: Security (for payments/auth), Monitoring, Rollback Plan, Testing Strategy
+- **Optional sections**: Success Metrics, Glossary, Alternatives Considered, Dependencies, Performance Requirements, and more
+
+The skill automatically adapts to:
+
+- **Project size**: Small (< 1 week), Medium (1-4 weeks), Large (> 1 month)
+- **Project type**: Integration, Feature, Refactor, Infrastructure, Payment, Auth, Data migration
+- **User's language**: Automatically generates TDD in Portuguese, English, or Spanish based on your request
+
+## How to Use
+
+### Basic Usage
+
+Simply ask the AI agent to create a TDD:
+
+**English:**
+
+```
+Create a TDD for Stripe payment integration
+```
+
+**Portuguese:**
+
+```
+Crie um TDD para integração com Stripe
+```
+
+**Spanish:**
+
+```
+Crea un TDD para integración con Stripe
+```
+
+### Interactive Workflow
+
+The skill will guide you through an interactive process:
+
+1. **Initial Questions**: Project name, size, type, and context clarity
+2. **Mandatory Information**: Problem statement, scope, technical approach
+3. **Critical Sections**: Security, monitoring, rollback (if applicable)
+4. **Optional Sections**: Success metrics, glossary, alternatives, etc.
+
+### Examples
+
+#### Example 1: Payment Integration
+
+**Your Request:**
+
+```
+Create a TDD for integrating Stripe payments into our subscription system
+```
+
+**What Happens:**
+
+1. Agent asks about project size and type
+2. Agent requests: problem statement, scope, technical approach
+3. Agent identifies this is a payment system → **Security section becomes MANDATORY**
+4. Agent asks for: security requirements, monitoring metrics, rollback plan
+5. Agent generates comprehensive TDD with all required sections
+
+**Result:** A complete TDD with:
+
+- Context and problem statement
+- In-scope/out-of-scope features
+- Architecture diagram
+- API contracts
+- Security considerations (PCI DSS compliance, encryption, PII handling)
+- Testing strategy
+- Monitoring & observability
+- Rollback plan
+- Implementation timeline
+
+#### Example 2: Simple Feature
+
+**Your Request:**
+
+```
+Write a design doc for adding user profile pictures
+```
+
+**What Happens:**
+
+1. Agent identifies this as a small feature
+2. Agent asks for basic information
+3. Agent generates streamlined TDD with essential sections only
+
+**Result:** A focused TDD with:
+
+- Context
+- Problem statement
+- Scope (in/out)
+- Technical solution (file upload, storage, API endpoints)
+- Risks
+- Implementation plan
+- Testing strategy
+
+#### Example 3: Migration Project
+
+**Your Request:**
+
+```
+Crie um TDD para migração do banco de dados PostgreSQL para MongoDB
+```
+
+**What Happens:**
+
+1. Agent detects Portuguese language → generates TDD in Portuguese
+2. Agent identifies this as a migration project
+3. Agent requests: migration strategy, data mapping, rollback plan
+4. Agent offers migration plan section
+
+**Result:** A TDD in Portuguese with:
+
+- Contexto (Context)
+- Definição do Problema (Problem Statement)
+- Escopo (Scope)
+- Solução Técnica (Technical Solution)
+- Plano de Migração (Migration Plan)
+- Plano de Rollback (Rollback Plan)
+- Estratégia de Testes (Testing Strategy)
+
+## What to Expect
+
+### The Agent Will Ask Questions
+
+The skill is designed to gather complete information. Expect questions like:
+
+**For Problem Statement:**
+
+- What problem are we solving?
+- Why is this important now?
+- What happens if we don't solve it?
+
+**For Scope:**
+
+- What WILL be delivered in V1?
+- What will NOT be included (out of scope)?
+
+**For Technical Approach:**
+
+- What are the main components?
+- How does data flow through the system?
+- What APIs will be created/modified?
+
+**For Payment/Auth Projects:**
+
+- How will you handle authentication?
+- What encryption will be used?
+- What PII is collected?
+- Any compliance requirements (GDPR, PCI DSS)?
+
+**For Production Systems:**
+
+- How will you monitor this?
+- What metrics matter?
+- How will you rollback if something fails?
+
+### The Generated TDD
+
+The TDD will include:
+
+1. **Header & Metadata**: Tech Lead, Team, Epic link, Status, Dates
+2. **Context**: Background, domain, stakeholders
+3. **Problem Statement**: Specific problems with quantified impact
+4. **Scope**: Clear in-scope and out-of-scope items
+5. **Technical Solution**: Architecture, data flow, APIs, database changes
+6. **Risks**: Risk matrix with impact, probability, and mitigation
+7. **Implementation Plan**: Phased breakdown with estimates
+8. **Security** (if applicable): Authentication, encryption, compliance
+9. **Testing Strategy**: Unit, integration, E2E test plans
+10. **Monitoring & Observability**: Metrics, alerts, dashboards
+11. **Rollback Plan**: Triggers and steps for reverting changes
+12. **Optional sections**: Success metrics, glossary, alternatives, dependencies, etc.
+
+## Tips for Best Results
+
+### 1. Provide Context Early
+
+Instead of:
+
+```
+Create a TDD for Stripe
+```
+
+Try:
+
+```
+Create a TDD for integrating Stripe payments. We need to support subscriptions,
+handle webhooks, and comply with PCI DSS. This is for our SaaS product.
+```
+
+### 2. Be Specific About Scope
+
+The agent will ask, but you can provide upfront:
+
+```
+Create a TDD for user authentication. In scope: email/password, JWT tokens,
+password reset. Out of scope: OAuth, 2FA, social login (those are V2).
+```
+
+### 3. Mention Project Size
+
+```
+Create a TDD for the database migration project. This is a large project
+(expected 2 months).
+```
+
+### 4. Specify Critical Requirements
+
+For payment/auth systems, mention security requirements:
+
+```
+Create a TDD for Stripe integration. We need PCI DSS compliance, webhook
+signature validation, and encrypted storage of payment method tokens.
+```
+
+### 5. Use Your Language
+
+The skill automatically detects your language. Just write naturally:
+
+- **English**: "Create a TDD for..."
+- **Portuguese**: "Crie um TDD para..."
+- **Spanish**: "Crea un TDD para..."
+
+## Language Support
+
+The skill supports multiple languages:
+
+| Language   | Example Trigger                           |
+| ---------- | ----------------------------------------- |
+| English    | "Create a TDD for Stripe integration"     |
+| Portuguese | "Crie um TDD para integração com Stripe"  |
+| Spanish    | "Crea un TDD para integración con Stripe" |
+
+All section headers and content are automatically translated to match your language.
+
+## Integration with Other Skills
+
+### Confluence Publishing
+
+After generating a TDD, the agent will offer to publish it to Confluence:
+
+```
+Would you like me to publish this TDD to Confluence?
+- I can create a new page in your space
+- Or update an existing page
+```
+
+### Jira Integration
+
+The TDD includes a metadata section for Epic/Ticket links. You can manually add these or ask the agent to help create Jira tickets.
+
+## What Makes This Skill Different
+
+### 1. Industry Standards
+
+Follows patterns from:
+
+- Google Design Docs
+- Amazon PR-FAQ (Working Backwards)
+- RFC Pattern
+- ADR (Architecture Decision Records)
+- SRE Book (Monitoring, Rollback, SLOs)
+- PCI DSS & OWASP (Security)
+
+### 2. Architecture-Focused, Not Implementation
+
+The TDD documents **decisions and contracts**, not code:
+
+✅ **Includes**: API contracts, data schemas, architecture diagrams, strategies
+❌ **Avoids**: CLI commands, code snippets, framework-specific implementation
+
+### 3. Adaptive to Project Size
+
+- **Small projects**: Essential sections only (7-9 sections)
+- **Medium projects**: Mandatory + critical sections (11-13 sections)
+- **Large projects**: All sections (up to 20 sections)
+
+### 4. Mandatory Sections Enforcement
+
+The agent will **insist** on completing mandatory sections before finalizing the TDD. You can't skip:
+
+- Problem Statement
+- Scope
+- Technical Solution
+- Risks
+- Implementation Plan
+
+### 5. Critical Sections for Specific Project Types
+
+- **Payment/Auth**: Security section is MANDATORY
+- **Production**: Monitoring and Rollback are MANDATORY
+- **Integration**: Dependencies and Security are highly recommended
+
+## Common Use Cases
+
+### ✅ Good Use Cases
+
+- New feature development
+- External API integration
+- System migration or refactoring
+- Infrastructure changes
+- Payment/billing system design
+- Authentication/authorization system
+- Data processing pipelines
+
+### ❌ Not Ideal For
+
+- Bug fixes (too small)
+- Code refactoring without architectural changes
+- Documentation updates
+- Simple configuration changes
+
+## Example Output Structure
+
+```
+# TDD - [Project Name]
+
+## Metadata
+- Tech Lead: @Name
+- Team: Name1, Name2
+- Status: Draft
+- Created: 2026-02-04
+
+## Context
+[Background and domain description]
+
+## Problem Statement & Motivation
+[Specific problems with impact]
+
+## Scope
+### ✅ In Scope
+[What will be delivered]
+
+### ❌ Out of Scope
+[What won't be included]
+
+## Technical Solution
+[Architecture, APIs, data flow, database changes]
+
+## Risks
+[Risk matrix with mitigation]
+
+## Implementation Plan
+[Phased breakdown with estimates]
+
+## Security Considerations
+[Authentication, encryption, compliance]
+
+## Testing Strategy
+[Unit, integration, E2E tests]
+
+## Monitoring & Observability
+[Metrics, alerts, dashboards]
+
+## Rollback Plan
+[Triggers and steps]
+
+[Additional optional sections...]
+```
+
+## Troubleshooting
+
+### The Agent Keeps Asking Questions
+
+**This is normal!** The skill is designed to gather complete information. Answer the questions to get a comprehensive TDD.
+
+### I Want to Skip a Section
+
+Mandatory sections cannot be skipped. For optional sections, you can say:
+
+```
+Skip the Alternatives Considered section for now
+```
+
+### The TDD is Too Detailed
+
+For small projects, specify the size:
+
+```
+This is a small project (< 1 week), keep it simple
+```
+
+### The TDD is Missing Something
+
+Tell the agent what's missing:
+
+```
+Add a section on performance requirements
+```
+
+## Next Steps After Creating a TDD
+
+1. **Review**: Check all sections are complete
+2. **Share**: Get feedback from team members
+3. **Approve**: Get sign-off from stakeholders
+4. **Implement**: Use the TDD as a guide during development
+5. **Update**: Keep the TDD updated as the project evolves
+
+## Support
+
+For issues or questions about this skill, refer to the main [agent-skills repository](https://github.com/tech-leads-club/agent-skills).