@bastani/atomic 0.5.15 → 0.5.16-0

package/.agents/skills/frontend-design/reference/ux-writing.md

@@ -1,107 +0,0 @@
-# UX Writing
-
-## The Button Label Problem
-
-**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
-
-| Bad | Good | Why |
-|-----|------|-----|
-| OK | Save changes | Says what will happen |
-| Submit | Create account | Outcome-focused |
-| Yes | Delete message | Confirms the action |
-| Cancel | Keep editing | Clarifies what "cancel" means |
-| Click here | Download PDF | Describes the destination |
-
-**For destructive actions**, name the destruction:
-- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
-- "Delete 5 items" not "Delete selected" (show the count)
-
-## Error Messages: The Formula
-
-Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
-
-### Error Message Templates
-
-| Situation | Template |
-|-----------|----------|
-| **Format error** | "[Field] needs to be [format]. Example: [example]" |
-| **Missing required** | "Please enter [what's missing]" |
-| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
-| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
-| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
-
-### Don't Blame the User
-
-Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
-
-## Empty States Are Opportunities
-
-Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
-
-## Voice vs Tone
-
-**Voice** is your brand's personality—consistent everywhere.
-**Tone** adapts to the moment.
-
-| Moment | Tone Shift |
-|--------|------------|
-| Success | Celebratory, brief: "Done! Your changes are live." |
-| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
-| Loading | Reassuring: "Saving your work..." |
-| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
-
-**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
-
-## Writing for Accessibility
-
-**Link text** must have standalone meaning—"View pricing plans" not "Click here". **Alt text** describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
-
-## Writing for Translation
-
-### Plan for Expansion
-
-German text is ~30% longer than English. Allocate space:
-
-| Language | Expansion |
-|----------|-----------|
-| German | +30% |
-| French | +20% |
-| Finnish | +30-40% |
-| Chinese | -30% (fewer chars, but same width) |
-
-### Translation-Friendly Patterns
-
-Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
-
-## Consistency: The Terminology Problem
-
-Pick one term and stick with it:
-
-| Inconsistent | Consistent |
-|--------------|------------|
-| Delete / Remove / Trash | Delete |
-| Settings / Preferences / Options | Settings |
-| Sign in / Log in / Enter | Sign in |
-| Create / Add / New | Create |
-
-Build a terminology glossary and enforce it. Variety creates confusion.
-
-## Avoid Redundant Copy
-
-If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
-
-## Loading States
-
-Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
-
-## Confirmation Dialogs: Use Sparingly
-
-Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
-
-## Form Instructions
-
-Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
-
----
-
-**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.

package/.agents/skills/normalize/SKILL.md

@@ -1,70 +0,0 @@
----
-name: normalize
-description: Audits and realigns UI to match design system standards, spacing, tokens, and patterns. Use when the user mentions consistency, design drift, mismatched styles, tokens, or wants to bring a feature back in line with the system.
-user-invocable: true
-argument-hint: "[feature (page, route, component...)]"
----
-
-Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.
-
-## MANDATORY PREPARATION
-
-Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first.
-
----
-
-## Plan
-
-Before making changes, deeply understand the context:
-
-1. **Discover the design system**: Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:
-   - Core design principles and aesthetic direction
-   - Target audience and personas
-   - Component patterns and conventions
-   - Design tokens (colors, typography, spacing)
-   
-   **CRITICAL**: If something isn't clear, ask. Don't guess at design system principles.
-
-2. **Analyze the current feature**: Assess what works and what doesn't:
-   - Where does it deviate from design system patterns?
-   - Which inconsistencies are cosmetic vs. functional?
-   - What's the root cause—missing tokens, one-off implementations, or conceptual misalignment?
-
-3. **Create a normalization plan**: Define specific changes that will align the feature with the design system:
-   - Which components can be replaced with design system equivalents?
-   - Which styles need to use design tokens instead of hard-coded values?
-   - How can UX patterns match established user flows?
-   
-   **IMPORTANT**: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.
-
-## Execute
-
-Systematically address all inconsistencies across these dimensions:
-
-- **Typography**: Use design system fonts, sizes, weights, and line heights. Replace hard-coded values with typographic tokens or classes.
-- **Color & Theme**: Apply design system color tokens. Remove one-off color choices that break the palette.
-- **Spacing & Layout**: Use spacing tokens (margins, padding, gaps). Align with grid systems and layout patterns used elsewhere.
-- **Components**: Replace custom implementations with design system components. Ensure props and variants match established patterns.
-- **Motion & Interaction**: Match animation timing, easing, and interaction patterns to other features.
-- **Responsive Behavior**: Ensure breakpoints and responsive patterns align with design system standards.
-- **Accessibility**: Verify contrast ratios, focus states, ARIA labels match design system requirements.
-- **Progressive Disclosure**: Match information hierarchy and complexity management to established patterns.
-
-**NEVER**:
-- Create new one-off components when design system equivalents exist
-- Hard-code values that should use design tokens
-- Introduce new patterns that diverge from the design system
-- Compromise accessibility for visual consistency
-
-This is not an exhaustive list—apply judgment to identify all areas needing normalization.
-
-## Clean Up
-
-After normalization, ensure code quality:
-
-- **Consolidate reusable components**: If you created new components that should be shared, move them to the design system or shared UI component path.
-- **Remove orphaned code**: Delete unused implementations, styles, or files made obsolete by normalization.
-- **Verify quality**: Lint, type-check, and test according to repository guidelines. Ensure normalization didn't introduce regressions.
-- **Ensure DRYness**: Look for duplication introduced during refactoring and consolidate.
-
-Remember: You are a brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.

package/.agents/skills/onboard/SKILL.md

@@ -1,245 +0,0 @@
----
-name: onboard
-description: Designs and improves onboarding flows, empty states, and first-run experiences to help users reach value quickly. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, or new user flows.
-user-invocable: true
-argument-hint: "[target]"
----
-
-## MANDATORY PREPARATION
-
-Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level.
-
----
-
-Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
-
-## Assess Onboarding Needs
-
-Understand what users need to learn and why:
-
-1. **Identify the challenge**:
-   - What are users trying to accomplish?
-   - What's confusing or unclear about current experience?
-   - Where do users get stuck or drop off?
-   - What's the "aha moment" we want users to reach?
-
-2. **Understand the users**:
-   - What's their experience level? (Beginners, power users, mixed?)
-   - What's their motivation? (Excited and exploring? Required by work?)
-   - What's their time commitment? (5 minutes? 30 minutes?)
-   - What alternatives do they know? (Coming from competitor? New to category?)
-
-3. **Define success**:
-   - What's the minimum users need to learn to be successful?
-   - What's the key action we want them to take? (First project? First invite?)
-   - How do we know onboarding worked? (Completion rate? Time to value?)
-
-**CRITICAL**: Onboarding should get users to value as quickly as possible, not teach everything possible.
-
-## Onboarding Principles
-
-Follow these core principles:
-
-### Show, Don't Tell
-- Demonstrate with working examples, not just descriptions
-- Provide real functionality in onboarding, not separate tutorial mode
-- Use progressive disclosure - teach one thing at a time
-
-### Make It Optional (When Possible)
-- Let experienced users skip onboarding
-- Don't block access to product
-- Provide "Skip" or "I'll explore on my own" options
-
-### Time to Value
-- Get users to their "aha moment" ASAP
-- Front-load most important concepts
-- Teach 20% that delivers 80% of value
-- Save advanced features for contextual discovery
-
-### Context Over Ceremony
-- Teach features when users need them, not upfront
-- Empty states are onboarding opportunities
-- Tooltips and hints at point of use
-
-### Respect User Intelligence
-- Don't patronize or over-explain
-- Be concise and clear
-- Assume users can figure out standard patterns
-
-## Design Onboarding Experiences
-
-Create appropriate onboarding for the context:
-
-### Initial Product Onboarding
-
-**Welcome Screen**:
-- Clear value proposition (what is this product?)
-- What users will learn/accomplish
-- Time estimate (honest about commitment)
-- Option to skip (for experienced users)
-
-**Account Setup**:
-- Minimal required information (collect more later)
-- Explain why you're asking for each piece of information
-- Smart defaults where possible
-- Social login when appropriate
-
-**Core Concept Introduction**:
-- Introduce 1-3 core concepts (not everything)
-- Use simple language and examples
-- Interactive when possible (do, don't just read)
-- Progress indication (step 1 of 3)
-
-**First Success**:
-- Guide users to accomplish something real
-- Pre-populated examples or templates
-- Celebrate completion (but don't overdo it)
-- Clear next steps
-
-### Feature Discovery & Adoption
-
-**Empty States**:
-Instead of blank space, show:
-- What will appear here (description + screenshot/illustration)
-- Why it's valuable
-- Clear CTA to create first item
-- Example or template option
-
-Example:
-```
-No projects yet
-Projects help you organize your work and collaborate with your team.
-[Create your first project] or [Start from template]
-```
-
-**Contextual Tooltips**:
-- Appear at relevant moment (first time user sees feature)
-- Point directly at relevant UI element
-- Brief explanation + benefit
-- Dismissable (with "Don't show again" option)
-- Optional "Learn more" link
-
-**Feature Announcements**:
-- Highlight new features when they're released
-- Show what's new and why it matters
-- Let users try immediately
-- Dismissable
-
-**Progressive Onboarding**:
-- Teach features when users encounter them
-- Badges or indicators on new/unused features
-- Unlock complexity gradually (don't show all options immediately)
-
-### Guided Tours & Walkthroughs
-
-**When to use**:
-- Complex interfaces with many features
-- Significant changes to existing product
-- Industry-specific tools needing domain knowledge
-
-**How to design**:
-- Spotlight specific UI elements (dim rest of page)
-- Keep steps short (3-7 steps max per tour)
-- Allow users to click through tour freely
-- Include "Skip tour" option
-- Make replayable (help menu)
-
-**Best practices**:
-- Interactive > passive (let users click real buttons)
-- Focus on workflow, not features ("Create a project" not "This is the project button")
-- Provide sample data so actions work
-
-### Interactive Tutorials
-
-**When to use**:
-- Users need hands-on practice
-- Concepts are complex or unfamiliar
-- High stakes (better to practice in safe environment)
-
-**How to design**:
-- Sandbox environment with sample data
-- Clear objectives ("Create a chart showing sales by region")
-- Step-by-step guidance
-- Validation (confirm they did it right)
-- Graduation moment (you're ready!)
-
-### Documentation & Help
-
-**In-product help**:
-- Contextual help links throughout interface
-- Keyboard shortcut reference
-- Search-able help center
-- Video tutorials for complex workflows
-
-**Help patterns**:
-- `?` icon near complex features
-- "Learn more" links in tooltips
-- Keyboard shortcut hints (`⌘K` shown on search box)
-
-## Empty State Design
-
-Every empty state needs:
-
-### What Will Be Here
-"Your recent projects will appear here"
-
-### Why It Matters  
-"Projects help you organize your work and collaborate with your team"
-
-### How to Get Started
-[Create project] or [Import from template]
-
-### Visual Interest
-Illustration or icon (not just text on blank page)
-
-### Contextual Help
-"Need help getting started? [Watch 2-min tutorial]"
-
-**Empty state types**:
-- **First use**: Never used this feature (emphasize value, provide template)
-- **User cleared**: Intentionally deleted everything (light touch, easy to recreate)
-- **No results**: Search or filter returned nothing (suggest different query, clear filters)
-- **No permissions**: Can't access (explain why, how to get access)
-- **Error state**: Failed to load (explain what happened, retry option)
-
-## Implementation Patterns
-
-### Technical approaches:
-
-**Tooltip libraries**: Tippy.js, Popper.js
-**Tour libraries**: Intro.js, Shepherd.js, React Joyride
-**Modal patterns**: Focus trap, backdrop, ESC to close
-**Progress tracking**: LocalStorage for "seen" states
-**Analytics**: Track completion, drop-off points
-
-**Storage patterns**:
-```javascript
-// Track which onboarding steps user has seen
-localStorage.setItem('onboarding-completed', 'true');
-localStorage.setItem('feature-tooltip-seen-reports', 'true');
-```
-
-**IMPORTANT**: Don't show same onboarding twice (annoying). Track completion and respect dismissals.
-
-**NEVER**:
-- Force users through long onboarding before they can use product
-- Patronize users with obvious explanations
-- Show same tooltip repeatedly (respect dismissals)
-- Block all UI during tour (let users explore)
-- Create separate tutorial mode disconnected from real product
-- Overwhelm with information upfront (progressive disclosure!)
-- Hide "Skip" or make it hard to find
-- Forget about returning users (don't show initial onboarding again)
-
-## Verify Onboarding Quality
-
-Test with real users:
-
-- **Time to completion**: Can users complete onboarding quickly?
-- **Comprehension**: Do users understand after completing?
-- **Action**: Do users take desired next step?
-- **Skip rate**: Are too many users skipping? (Maybe it's too long/not valuable)
-- **Completion rate**: Are users completing? (If low, simplify)
-- **Time to value**: How long until users get first value?
-
-Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.

package/.agents/skills/teach-impeccable/SKILL.md

@@ -1,71 +0,0 @@
----
-name: teach-impeccable
-description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.
-user-invocable: true
----
-
-Gather design context for this project, then persist it for all future sessions.
-
-## Step 1: Explore the Codebase
-
-Before asking questions, thoroughly scan the project to discover what you can:
-
-- **README and docs**: Project purpose, target audience, any stated goals
-- **Package.json / config files**: Tech stack, dependencies, existing design libraries
-- **Existing components**: Current design patterns, spacing, typography in use
-- **Brand assets**: Logos, favicons, color values already defined
-- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
-- **Any style guides or brand documentation**
-
-Note what you've learned and what remains unclear.
-
-## Step 2: Ask UX-Focused Questions
-
-ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
-
-### Users & Purpose
-- Who uses this? What's their context when using it?
-- What job are they trying to get done?
-- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)
-
-### Brand & Personality
-- How would you describe the brand personality in 3 words?
-- Any reference sites or apps that capture the right feel? What specifically about them?
-- What should this explicitly NOT look like? Any anti-references?
-
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
-### Accessibility & Inclusion
-- Specific accessibility requirements? (WCAG level, known user needs)
-- Considerations for reduced motion, color blindness, or other accommodations?
-
-Skip questions where the answer is already clear from the codebase exploration.
-
-## Step 3: Write Design Context
-
-Synthesize your findings and the user's answers into a `## Design Context` section:
-
-```markdown
-## Design Context
-
-### Users
-[Who they are, their context, the job to be done]
-
-### Brand Personality
-[Voice, tone, 3-word personality, emotional goals]
-
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
-
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
-```
-
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
-
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .github/copilot-instructions.md. If yes, append or update the section there as well.
-
-Confirm completion and summarize the key design principles that will now guide all future work.