@equal-experts/kuat-react 0.2.3 → 0.2.5

package/docs/content/content-foundations.md

@@ -0,0 +1,506 @@
+# Kuat Design System Content Foundations
+
+---
+**Version:** 1.0  
+**Last Updated:** December 2024  
+**Type:** Universal Guidelines  
+**Audience:** All content creators  
+**Dependencies:** None (base file)
+
+---
+
+## How to Use This Guide
+
+This document contains the **universal principles** that apply to ALL Kuat Design System content.
+
+**Getting started:**
+- 🆕 New to the Kuat Design System? Read this document completely
+- 📝 Creating marketing content? Read this, then see [`content-marketing-sales.md`](./content-marketing-sales.md)
+- 🎨 Writing UX copy? Read this, then see [`content-product-ux.md`](./content-product-ux.md)
+- 🤖 AI agent? Load this file first, then the relevant specialized guide
+
+**All content must align with these foundations.**
+
+---
+
+## 30-Second Quick Reference
+
+**Always:**
+- Be clear and direct
+- Focus on user needs
+- Use plain language
+- Be specific, not vague
+
+**Never:**
+- Use "revolutionize", "transform", "disrupt" without specific evidence
+- Hide behind jargon
+- Speak down to audience
+- Be vague or ambiguous
+
+**The Kuat Design System content formula:**
+
+**For marketing content:**
+`[Clear value] + [specific context] + [evidence/examples] + [actionable takeaways]`
+
+**For product content:**
+`[Action] + [Object] + [Benefit if needed]`
+
+**Example (Marketing):** "The Kuat Design System provides a consistent component library that reduced development time by 40% while maintaining brand consistency across React and Vue applications."
+
+**Example (Product):** "Save invoice"
+
+---
+
+## Content Voice and Tone
+
+### Universal Principles (Apply to ALL content)
+
+#### We are clear and direct
+- Get to the point quickly
+- Use plain language
+- Avoid unnecessary words
+- Be specific, not vague
+
+#### We are helpful and respectful
+- Anticipate user needs
+- Provide guidance when needed
+- Respect user's time and intelligence
+- Never talk down to users
+
+#### We are confident but humble
+- Show expertise through clarity
+- Admit when something isn't available
+- Provide alternatives when possible
+- Build trust through honesty
+
+#### We are consistent and predictable
+- Use the same terms for the same concepts
+- Follow established patterns
+- Maintain consistent tone across touchpoints
+- Set clear expectations
+
+---
+
+## Content Principles
+
+### 1. User-First Thinking
+
+Before creating content, define:
+- The specific aim
+- The target audience
+- How it helps users achieve their goals
+- What question it answers
+
+### 2. Clarity Over Cleverness
+
+Prioritize:
+- ✅ Clear communication
+- ✅ Easy comprehension
+- ✅ Quick understanding
+
+Avoid:
+- ❌ Clever wordplay that obscures meaning
+- ❌ Jokes that might confuse
+- ❌ Metaphors that require explanation
+- ❌ Industry jargon without context
+
+### 3. Be Clear and Concise
+
+- Use plain English where possible
+- Don't use 10 words when 3 will do
+- Avoid jargon-laden complexity
+- Give yourself the best chance of being read and understood
+
+### 4. Consistency Matters
+
+- Use the same terms for the same concepts
+- Follow established patterns
+- Maintain consistent tone
+- Set clear expectations
+
+### 5. Test, Iterate and Learn
+
+Test new content, improve based on feedback, share learnings across the team.
+
+---
+
+## Audience Considerations
+
+Use this guide to calibrate your tone and approach based on your audience.
+
+### Technical Audiences (Developers, Engineers, Architects)
+
+**Who they are:**
+- Deep technical knowledge
+- Responsible for implementation decisions
+- Value evidence and examples
+- Time-poor and appreciate directness
+
+**Tone:** Pragmatic, evidence-based, respectful of expertise
+
+**Avoid:**
+- Over-simplification of technical concepts
+- Buzzwords without substance
+- Marketing language
+- Talking down to their expertise
+
+**Use:**
+- "The component uses React hooks for state management..."
+- "Implementation example: [code]"
+- Specific technical details, trade-offs, architectural decisions
+- Code examples and practical patterns
+
+**Example:**
+✅ "The Button component uses `class-variance-authority` for variant management. Here's the implementation pattern: [code example]"
+
+❌ "Our revolutionary button component will transform your user experience with cutting-edge technology."
+
+---
+
+### Business Stakeholders (Product Owners, Business Leaders)
+
+**Who they are:**
+- Focus on business outcomes and ROI
+- Less interested in technical details
+- Need to understand impact and value
+- Accountable for business results
+
+**Tone:** Outcome-focused, clear, strategic
+
+**Avoid:**
+- Deep technical detail without business context
+- Acronyms and jargon without explanation
+- Focusing on technology for technology's sake
+- Vague promises without specifics
+
+**Use:**
+- "This translates to..."
+- "The business impact was..."
+- "Teams typically see..."
+- Business metrics, user outcomes, efficiency gains
+
+**Example:**
+✅ "The design system reduced component development time by 40%, allowing teams to ship features faster while maintaining consistency."
+
+❌ "We implemented a comprehensive component library using React, TypeScript, Tailwind CSS v4, and shadcn/ui patterns with Radix UI primitives."
+
+---
+
+### Product Teams (Product Managers, Designers, User Researchers)
+
+**Who they are:**
+- Focus on user needs and product outcomes
+- Balance business goals with user experience
+- Collaborate across disciplines
+- Need to understand both strategy and execution
+
+**Tone:** User-centered, collaborative, practical, insight-driven
+
+**Avoid:**
+- Pure technical implementation details
+- Business jargon without user context
+- Ignoring user research and feedback
+- Feature-focused language without outcomes
+
+**Use:**
+- "Users needed to..."
+- "Research showed that..."
+- "Working with the product team, we discovered..."
+- User outcomes, usability improvements, adoption metrics
+
+**Example:**
+✅ "User testing revealed that 68% of users struggled with the form. We simplified the flow and saw completion rates increase from 42% to 79%."
+
+❌ "We optimized the form validation logic using advanced regex patterns and implemented real-time field validation with debounced API calls."
+
+---
+
+### End Users (In Product Interfaces)
+
+**Who they are:**
+- Using the product to accomplish a task
+- Not interested in company marketing
+- Need clarity and speed
+- May be stressed or time-pressured
+
+**Tone:** Helpful, concise, action-oriented, respectful
+
+**Avoid:**
+- Any unnecessary words
+- Corporate speak or marketing language
+- Jargon or technical terms
+- Apologies or uncertainty
+
+**Use:**
+- Direct action verbs
+- Clear outcomes
+- Plain language
+- Confidence and clarity
+
+**Example:**
+✅ "Save invoice"
+✅ "Payment received"
+✅ "Email address required"
+
+❌ "You can now leverage our innovative invoice transmission functionality"
+❌ "We're sorry, but it appears there may have been an issue"
+
+---
+
+## Common Anti-Patterns to Avoid
+
+Recognize and avoid these common mistakes:
+
+### The "Buzzword Bingo"
+**What it is:** Using trendy terminology without substance or clarity
+
+❌ "Leveraging synergistic blockchain-enabled AI solutions to disrupt the paradigm"  
+❌ "Our transformative digital journey optimization platform"  
+❌ "We deliver agile, cloud-native, AI-powered innovation at scale"
+
+✅ "We automated invoice processing using existing APIs"  
+✅ "The team adopted incremental deployment practices"  
+✅ "We integrated machine learning to suggest expense categories"
+
+**Why it's wrong:** Obscures meaning, sounds generic, doesn't respect audience intelligence
+
+---
+
+### The "Feature Dump"
+**What it is:** Listing features or technologies without context or benefit
+
+❌ "The solution includes React, TypeScript, GraphQL, PostgreSQL, Redis, Kubernetes, and Docker"  
+❌ "Features: Dashboard, Reports, Analytics, Integrations, API, Mobile App"
+
+✅ "We chose React and TypeScript to enable their front-end team to maintain and extend the system confidently"  
+✅ "The dashboard surfaces the three metrics that procurement teams check daily, reducing time spent in spreadsheets"
+
+**Why it's wrong:** Doesn't explain value, doesn't show outcomes, assumes audience cares about technology choices
+
+---
+
+### The "Vague Promise"
+**What it is:** Making claims without evidence or specifics
+
+❌ "We'll dramatically improve your performance"  
+❌ "Our approach delivers exceptional results"  
+❌ "You'll see significant cost savings"
+
+✅ "In similar projects, teams typically see 40-60% reduction in deployment time"  
+✅ "The approach reduced our previous client's infrastructure costs by 35%"  
+✅ "Specific outcomes depend on context, but we'll measure and share progress weekly"
+
+**Why it's wrong:** Not evidence-based, sounds like every other solution, doesn't build trust
+
+---
+
+### The "Over-Explanation"
+**What it is:** Explaining things that don't need explanation
+
+❌ "Click the button below to continue to the next screen"  
+❌ "Please note that you may wish to save your work before proceeding"
+
+✅ [Continue]  
+✅ "Save your work before continuing"
+
+**Why it's wrong:** Wastes user's time, condescending, adds unnecessary friction
+
+---
+
+## Content Quality Checklist
+
+Every piece of content should pass these tests before publication:
+
+### The Clarity Test
+**Question:** Can it be understood in 30 seconds of skimming?
+
+- If **no** → Improve structure, add headings, cut fluff
+- If **yes** → Structure serves busy readers
+
+**Application:** Have someone unfamiliar with the content skim it for 30 seconds, then ask what they learned.
+
+---
+
+### The Purpose Test
+**Question:** Does this answer a specific question or solve a problem?
+
+- If **no** → Clarify purpose or don't publish
+- If **yes** → Content serves a clear need
+
+**Application:** Complete this sentence: "After reading this, the audience will be able to ________"
+
+---
+
+### The Consistency Test
+**Question:** Does it use consistent terminology and follow established patterns?
+
+- If **no** → Align with design system terminology
+- If **yes** → Consistency maintained
+
+**Application:** Check for:
+- Consistent use of design system terms
+- Matching tone with similar content
+- Following established patterns
+
+---
+
+### The Audience Test
+**Question:** Is this appropriate for the intended audience's knowledge and needs?
+
+- If **no** → Adjust complexity, context, or tone
+- If **yes** → Audience fit is appropriate
+
+**Application:** Reference the [Audience Considerations](#audience-considerations) section and verify alignment.
+
+---
+
+### The Accessibility Test
+**Question:** Does it work for all users, including those using assistive technologies?
+
+- If **no** → Improve accessibility
+- If **yes** → Accessible to all users
+
+**Application:** Check for:
+- Screen reader compatibility
+- Clear without visual context
+- Inclusive language
+- Proper heading hierarchy
+
+---
+
+## Tone Adaptation Guide
+
+Content type and audience determine specific tone adjustments while maintaining core voice principles.
+
+### Moving Between Content Types
+
+**Case Study → Blog:**
+- Case Study: "Working with the client, we identified..."
+- Blog: "When I worked on this project, we discovered..."
+- **Change:** Personal voice emerges, storytelling becomes more narrative
+
+**Playbook → Product UI:**
+- Playbook: "This approach helps teams align before delivery"
+- Product UI: "Align your team · Start inception"
+- **Change:** Extreme conciseness, action-orientation
+
+**External Content → Internal Content:**
+- External: "We work collaboratively with clients"
+- Internal: "Remember to involve client teams from day one"
+- **Change:** More direct, assumes shared context
+
+---
+
+### Adjusting for Seriousness
+
+**Standard (Most Content):**
+- Friendly, approachable, professional
+- "Working with their team, we refactored the service"
+
+**High Stakes (Security, Incidents, Compliance):**
+- Serious, direct, solution-focused
+- "The security incident was contained within 2 hours. Here's what we learned..."
+
+**Celebratory (Wins, Launches, Milestones):**
+- Warm, enthusiastic, appreciative
+- "Great work by the team! After 6 months of collaboration, the platform launched successfully."
+
+**Difficult News (Project challenges, setbacks):**
+- Empathetic, honest, supportive
+- "This decision was difficult. Here's what it means and how we'll support the team."
+
+---
+
+## For AI Content Generation
+
+### Before Generating Content
+
+**Confirm the following:**
+1. **Content type** - What format? (case study, blog, UI copy, etc.)
+2. **Audience** - Who will read this? (reference Audience Considerations)
+3. **Purpose** - What specific outcome does this serve?
+4. **Context** - Do I have enough information about the project/situation?
+
+**If any are unclear, ask clarifying questions before proceeding.**
+
+---
+
+### While Generating Content
+
+**Do:**
+- Use specific examples where possible
+- Include evidence or data when claiming results
+- Default to plain English, escalate technical detail only when needed
+- Apply appropriate tone from Audience Considerations
+- Reference design system components and patterns accurately
+
+**Don't:**
+- Generate generic content that could be from anyone
+- Make claims without evidence or qualification
+- Use phrases like "revolutionize", "transform", "disrupt" without specific proof
+- Write in ways that sound like typical AI-generated content
+- Ignore audience context
+
+---
+
+### After Generating Content
+
+**Apply these tests:**
+1. **The Clarity Test** - Can it be understood quickly?
+2. **The Purpose Test** - Does it serve a clear user need?
+3. **The Consistency Test** - Does it match our voice?
+4. **The Audience Test** - Is tone appropriate for the intended audience?
+5. **The Accessibility Test** - Does it work for all users?
+
+**Check for these red flags:**
+- Generic phrases that could apply to any system
+- Lack of specific examples or evidence
+- Over-use of buzzwords or jargon
+- Tone mismatch with audience
+- Missing accessibility considerations
+
+**Before finalizing:**
+- Verify tone matches both content type AND audience
+- Ensure all claims have evidence or appropriate qualification
+- Remove any phrase that sounds like generic AI writing
+- Confirm alignment with Kuat Design System voice
+
+---
+
+## Decision Tree: Which Guide Do I Need?
+
+Use this decision tree to determine which specialized guide to consult:
+
+**START:** What are you creating?
+
+**Is this content inside a product interface?**
+- YES → [`content-product-ux.md`](./content-product-ux.md)
+- NO → Continue
+
+**Is this content for external audiences about our work/expertise?**
+- YES → [`content-marketing-sales.md`](./content-marketing-sales.md)
+- NO → Continue
+
+**Is this internal team communication or documentation?**
+- YES → [`content-marketing-sales.md`](./content-marketing-sales.md) (Internal sections)
+- NO → Continue
+
+**Still unsure?**
+- Start with this foundations document
+- Ask: "Who is the audience and what's the purpose?"
+- Reference the Audience Considerations above
+
+---
+
+## Additional Resources
+
+- **Marketing Content Guide:** See [content-marketing-sales.md](./content-marketing-sales.md) for marketing, sales, and knowledge content
+- **Product Content Guide:** See [content-product-ux.md](./content-product-ux.md) for product interface content
+- **Design System Overview:** See [../design/design-system.md](../design/design-system.md) for design token usage
+- **Typography Guide:** See [../design/typography.md](../design/typography.md) for text styling
+- **Component Guidelines:** See [../technical/component-guidelines.md](../technical/component-guidelines.md) for component patterns
+
+---
+
+**Remember:** These are foundations that guide all Kuat Design System content. Use them as a framework, not a straitjacket. When in doubt, ask yourself: "Does this sound like something a knowledgeable, helpful, honest person would say to help someone accomplish their goal?" If yes, you're probably on the right track.
+