get-shit-pretty 0.2.0 → 0.4.0

package/templates/phases/build.md

@@ -1,59 +1,35 @@
-# Design-to-Code
+# Build
 
-## Project: {PROJECT_NAME}
-**Tech Stack:** {TECH_STACK}
-**Date:** {DATE}
+> Phase: build | Project: {PROJECT_NAME} | Generated: {DATE}
 
----
+## Chunks
 
-## Component Hierarchy
-```
-App
-├── Layout
-│   ├── Header
-│   ├── Navigation
-│   ├── Main
-│   └── Footer
-├── Pages
-│   ├── {PAGE_1}
-│   └── {PAGE_2}
-└── Shared
-    ├── {COMPONENT_1}
-    └── {COMPONENT_2}
-```
+### `build/CODE.md`
 
-## Components
+Main build manifest containing:
 
-### {COMPONENT_NAME}
-- **Props:** {PROPS}
-- **State:** {STATE}
-- **Data flow:** {DATA_FLOW}
-- **Responsive:** {RESPONSIVE_BEHAVIOR}
-- **Accessibility:** {ARIA_ROLES}
-- **States:** Default, Loading, Error, Empty
+1. **Component Hierarchy** — Tree diagram showing app structure with props and state annotations
+2. **Setup** — Token configuration (CSS variables or Tailwind config), theme provider, global styles
+3. **Component Index** — Table of all components with file paths
 
-```{LANGUAGE}
-// Implementation
+```markdown
+| Component | File | Props | States |
+|-----------|------|-------|--------|
+| {Component} | [components/{name}.md](./components/{name}.md) | {props} | {states} |
 ```
 
-<!-- Repeat for each component -->
-
-## Styling
-- **Approach:** {CSS_MODULES/TAILWIND/STYLED_COMPONENTS}
-- **Design tokens:** Mapped from `tokens.json`
-- **Dark mode:** {STRATEGY}
-- **Breakpoints:** {BREAKPOINTS}
+### `build/components/`
 
-## Animations
-| Element | Trigger | Animation | Duration | Easing |
-|---------|---------|-----------|----------|--------|
-| | | | | |
+Individual component files, one per component:
 
-## Performance
-- {OPTIMIZATION_1}
-- {OPTIMIZATION_2}
+| Component | File | ~Lines |
+|-----------|------|--------|
+| {Component} | [{name}.md](./components/{name}.md) | ~{N} |
 
-## Testing Strategy
-- **Unit:** {APPROACH}
-- **Visual regression:** {APPROACH}
-- **Accessibility:** {APPROACH}
+Each component file contains:
+- Full implementation code (copy-paste ready)
+- Props interface / types
+- All states (default, loading, error, empty)
+- Responsive behavior
+- Accessibility (ARIA, keyboard, focus)
+- Usage example

package/templates/phases/critique.md

@@ -0,0 +1,68 @@
+# Design Critique
+
+## Project: {PROJECT_NAME}
+**Date:** {DATE}
+**Reviewer:** GSP Design Critic + Accessibility Auditor
+
+---
+
+> This phase produces 6 chunks + INDEX.md in the `critique/` directory (4 from critic, 2 from auditor).
+
+## Chunk Mapping
+
+### Critic Chunks
+
+| Chunk File | Content |
+|-----------|---------|
+| `critique.md` | Nielsen's 10 heuristics scored 1-5, overall score X/50, visual hierarchy, typography & color, usability |
+| `prioritized-fixes.md` | Critical / Important / Polish fix lists with specific remediation |
+| `alternative-directions.md` | 2 redesign approaches with descriptions |
+| `strengths.md` | Specific design strengths to preserve |
+
+### Auditor Chunks
+
+| Chunk File | Content |
+|-----------|---------|
+| `accessibility-audit.md` | WCAG 2.2 AA checklist (Perceivable, Operable, Understandable, Robust, Mobile, Cognitive), conformance summary, statement draft |
+| `accessibility-fixes.md` | Violations table — issue, severity (Critical/Major), WCAG criterion, remediation steps |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### critique.md
+- **Heuristics evaluation:** 10 heuristics table (Heuristic, Score 1-5, Notes)
+- **Overall score:** X/50
+- **Visual hierarchy:** assessment
+- **Typography & color:** assessment
+- **Usability:** assessment
+- **Strategic alignment:** assessment
+
+### prioritized-fixes.md
+- **Critical (Must Fix):** numbered list with specific remediation per screen/component
+- **Important (High Priority):** numbered list
+- **Polish (If Time Allows):** numbered list
+- Links to `critique.md` and `accessibility-fixes.md`
+
+### alternative-directions.md
+- 2 redesign approaches each with: name, description, trade-offs
+
+### strengths.md
+- Specific strengths to preserve
+- What's working well and why
+
+### accessibility-audit.md
+- **Perceivable:** alt text, captions, color contrast (4.5:1 text, 3:1 large), text resizable
+- **Operable:** keyboard access, focus indicators, skip navigation, motion alternatives
+- **Understandable:** language declared, clear errors, contextual help
+- **Robust:** valid markup, ARIA roles correct
+- **Mobile:** orientation, touch targets (44x44pt), reachable UI
+- **Cognitive:** reading level, consistent navigation, no flashing, no time limits
+- **Summary:** total pass/fail/not-applicable counts, overall conformance level
+- **Accessibility statement:** draft
+
+### accessibility-fixes.md
+- Violations table: Issue, Severity (Critical/Major/Minor), WCAG Criterion, Remediation
+- Only Critical and Major severity items get detailed remediation steps
+- Links to `prioritized-fixes.md` (from critic agent)
+- References specific screens: `../design/screen-{NN}-{name}.md`

package/templates/phases/design.md

@@ -1,48 +1,70 @@
-# UI/UX Screens
+# UI/UX Design
 
 ## Project: {PROJECT_NAME}
 **Date:** {DATE}
 
 ---
 
-## User Personas
+> This phase produces screen chunks (`screen-{NN}-{name}.md`) + shared chunks in `design/shared/` + INDEX.md in the `design/` directory.
 
-### Primary Persona: {NAME}
-- **Demographics:** {DEMOGRAPHICS}
-- **Goals:** {GOALS}
-- **Pain points:** {PAIN_POINTS}
-- **Context:** {USAGE_CONTEXT}
+## Chunk Mapping
 
-## Information Architecture
-<!-- Hierarchy and navigation structure -->
+### Screen Chunks (`design/`)
 
-## Navigation Pattern
-- **Type:** {TAB_BAR/SIDEBAR/HAMBURGER/etc}
-- **Primary nav:** {ITEMS}
-- **Secondary nav:** {ITEMS}
+| Chunk File | Content |
+|-----------|---------|
+| `screen-{NN}-{name}.md` | One per screen — layout, components, states, interactions, accessibility |
 
-## Core Screens
+Naming: `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`, `screen-03-user-profile.md`)
 
-### Screen 1: {SCREEN_NAME}
-- **Purpose:** {PURPOSE}
-- **User flow:** {FLOW}
-- **Layout:** {LAYOUT_DESCRIPTION}
-- **Components used:** {COMPONENTS}
+### Shared Chunks (`design/shared/`)
+
+| Chunk File | Content |
+|-----------|---------|
+| `shared/personas.md` | User personas — demographics, goals, pain points, usage context |
+| `shared/information-architecture.md` | Content hierarchy and grouping |
+| `shared/navigation.md` | Nav pattern, items, responsive behavior |
+| `shared/micro-interactions.md` | Trigger → animation → duration → easing table |
+| `shared/responsive.md` | Mobile, tablet, desktop breakpoint adaptations |
+| `shared/component-plan.md` | Reuse / Refactor / New (shared) / New (local) — omit when target is `figma` |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### screen-{NN}-{name}.md
+- **Purpose:** what this screen does
+- **User flow:** position in the flow
+- **Layout:** wireframe-level description
+- **Components used:** from brand design system
 - **States:** Default, Empty, Loading, Error
-- **Interactions:** {INTERACTIONS}
-- **Accessibility:** {A11Y_NOTES}
+- **Interactions:** gestures, transitions
+- **Accessibility:** VoiceOver order, focus management
+
+### shared/personas.md
+- 2-3 personas each with: Name, Demographics, Goals, Pain points, Usage context
+
+### shared/information-architecture.md
+- Hierarchy and navigation structure
+- Content grouping rationale
 
-<!-- Repeat for 8 core screens -->
+### shared/navigation.md
+- **Type:** Tab bar / Sidebar / Hamburger / etc.
+- **Primary nav:** items
+- **Secondary nav:** items
+- Responsive behavior
 
-## Gestures & Micro-interactions
-| Trigger | Animation | Duration | Easing |
-|---------|-----------|----------|--------|
-| | | | |
+### shared/micro-interactions.md
+- Table: Trigger, Animation, Duration, Easing
+- Gesture definitions
 
-## Responsive Behavior
-- **Mobile:** {BEHAVIOR}
-- **Tablet:** {BEHAVIOR}
-- **Desktop:** {BEHAVIOR}
+### shared/responsive.md
+- **Mobile:** behavior
+- **Tablet:** behavior
+- **Desktop:** behavior
 
-## Designer's Notes
-{NOTES}
+### shared/component-plan.md
+- **Reuse (as-is):** Component, Source, Screens Used
+- **Refactor (needs changes):** Component, Source, Changes Needed, Screens Used
+- **New (shared):** Component, Purpose, Screens Used
+- **New (local):** Component, Screen, Purpose

package/templates/phases/discover.md

@@ -0,0 +1,60 @@
+# Brand Discovery
+
+## Brand: {BRAND_NAME}
+**Date:** {DATE}
+
+---
+
+> This phase produces 7 chunks + INDEX.md in the `discover/` directory.
+
+## Inputs
+- BRIEF.md — company, industry, audience, personality, goals
+- audit/ (if exists): brand-inventory.md, market-fit.md, evolution-map.md
+- config.json — brand_mode, evolution_scope
+
+## Chunk Mapping
+
+| Chunk File | Content |
+|-----------|---------|
+| `market-landscape.md` | Industry overview, market trends |
+| `competitive-audit.md` | Competitor analysis, positioning map, competitive gaps |
+| `swot-analysis.md` | Strengths, Weaknesses, Opportunities, Threats |
+| `audience-personas.md` | 2-3 personas with demographics, goals, pain points |
+| `trend-analysis.md` | Design and cultural trends, user expectation shifts |
+| `strategic-recommendations.md` | 3 actionable recommendations |
+| `mood-board-direction.md` | Color, typography, imagery direction |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### market-landscape.md
+- Industry overview and analysis
+- Market size, key players
+- Where the industry is heading
+
+### competitive-audit.md
+- Competitor table: Positioning, Strengths, Weaknesses, Visual Style
+- 2x2 positioning map on strategic axes
+- Competitive gaps and opportunities
+
+### swot-analysis.md
+- Strengths / Weaknesses / Opportunities / Threats matrix
+- Design-focused analysis
+
+### audience-personas.md
+- 2-3 personas each with: Demographics, Goals, Pain points, Brand expectations, Media habits
+
+### trend-analysis.md
+- 5 macro trends with: definition, visual language, adoption phase, 3 brand examples, risks/opportunities
+- User expectation shifts
+- Platform evolution
+
+### strategic-recommendations.md
+- 3 specific, actionable recommendations for this brand
+
+### mood-board-direction.md
+- Color direction (hex values)
+- Typography direction (named typefaces)
+- Imagery direction
+- Overall feel

package/templates/phases/identity.md

@@ -0,0 +1,78 @@
+# Visual Identity
+
+## Brand: {BRAND_NAME}
+**Date:** {DATE}
+
+---
+
+> This phase produces 6 chunks + palettes.json + INDEX.md in the `identity/` directory.
+
+## Inputs
+- BRIEF.md — audience, constraints
+- discover/mood-board-direction.md → color direction (hex), typography (typefaces), imagery
+- strategy/brand-prism.md Physique → logo concept, visual form
+- strategy/archetype.md visual tendencies → color warmth, type energy, imagery style
+- strategy/positioning.md → visual differentiation
+- strategy/brand-platform.md → values as visual language
+- verbal/brand-voice.md → typography warmth, color energy
+- verbal/tone-spectrum.md → visual energy level
+- audit/brand-inventory.md (if exists) → current visual elements as evolution baseline
+- audit/evolution-map.md (if exists) → preserve/evolve/replace decisions
+
+## Chunk Mapping
+
+| Chunk File | Content |
+|-----------|---------|
+| `logo-directions.md` | 3 logo directions with concept, rationale, variations, usage rules |
+| `color-system.md` | Full palette table, semantic colors, dark mode mapping, contrast ratios |
+| `typography.md` | Primary + secondary typefaces, full type scale, responsive behavior |
+| `imagery-style.md` | Photography, illustration, iconography guidelines |
+| `brand-applications.md` | Key touchpoints showing the brand in use |
+| `brand-book.md` | 20-page brand book outline with section descriptions |
+
+Also produces `palettes.json` — machine-readable OKLCH color scales.
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### logo-directions.md
+- 3 directions each with:
+  - **Concept:** description
+  - **Strategic rationale:** why this direction
+  - **Variations:** Primary, Secondary, Icon, Monochrome
+  - **Clear space:** rules
+  - **Minimum size:** min size
+  - **Usage rules:** rules
+
+### color-system.md
+- Full palette table: Role, Hex, RGB, Pantone, CMYK, Usage, Rationale
+- Semantic colors (error, success, warning)
+- Color rationale — how colors connect to brand strategy and archetype
+- Dark mode mapping table: Light Mode → Dark Mode
+- Contrast ratios table: Combination, Ratio, Pass/Fail (WCAG AA)
+- Reference to `./palettes.json` for machine-readable OKLCH scales
+
+### typography.md
+- **Primary typeface:** name, rationale (connect to verbal tone), weights, use cases
+- **Secondary typeface:** name, rationale, weights, use cases
+- Type scale table: Level, Size, Weight, Line Height, Use
+- Responsive behavior notes
+
+### imagery-style.md
+- **Photography direction:** style, subjects, color treatment, composition, don'ts
+- **Illustration style:** style, complexity, color palette
+- **Iconography:** style, weight, grid, corner radius
+
+### brand-applications.md
+- Key touchpoints showing the brand in use (digital, print, social)
+- Each application with visual direction and design notes
+
+### brand-book.md
+- 20-page outline:
+  1. Cover — 2. Brand Story — 3. Brand Prism — 4. Brand Voice
+  5. Logo System — 6. Logo Usage Rules — 7. Color System — 8. Color Applications
+  9. Typography — 10. Type in Use — 11. Imagery Direction — 12. Photography Guidelines
+  13. Illustration Guidelines — 14. Iconography — 15. Layout & Grid
+  16. Brand Applications (Digital) — 17. Brand Applications (Print)
+  18. Brand Applications (Social) — 19. Do's and Don'ts — 20. Contact & Resources

package/templates/phases/launch.md

@@ -5,58 +5,51 @@
 
 ---
 
-## Campaign Strategy
-- **Objective:** {OBJECTIVE}
-- **Target audience:** {AUDIENCE}
-- **Key message:** {MESSAGE}
-- **Tone:** {TONE}
-
-## Digital Ads
-
-### Google Ads
-| Format | Headline | Description | CTA | Visual Direction |
-|--------|----------|-------------|-----|-----------------|
-| | | | | |
-
-### Meta / Instagram
-| Format | Copy | Visual Direction | CTA | A/B Variant |
-|--------|------|-----------------|-----|-------------|
-| | | | | |
-
-### TikTok
-| Format | Hook | Copy | Visual Direction |
-|--------|------|------|-----------------|
-| | | | |
-
-## Email Sequences
-
-### Welcome Series
-1. **Email 1:** {SUBJECT} — {PURPOSE}
-2. **Email 2:** {SUBJECT} — {PURPOSE}
-3. **Email 3:** {SUBJECT} — {PURPOSE}
-
-### Promotional
-- {EMAIL_SPEC}
-
-### Re-engagement
-- {EMAIL_SPEC}
-
-## Landing Page
-- **Headline:** {HEADLINE}
-- **Subhead:** {SUBHEAD}
-- **Hero:** {VISUAL_DIRECTION}
-- **CTA:** {CTA}
-- **Social proof:** {APPROACH}
-
-## Social Media
-| Platform | Post Type | Copy | Visual Direction | Hashtags |
-|----------|-----------|------|-----------------|----------|
-| | | | | |
-
-## Sales Enablement
-- {MATERIAL_1}
-- {MATERIAL_2}
-
-## Content Marketing
-- {CONTENT_1}
-- {CONTENT_2}
+> This phase produces 6 chunks + INDEX.md in the `launch/` directory.
+
+## Chunk Mapping
+
+| Chunk File | Content |
+|-----------|---------|
+| `campaign-strategy.md` | Objective, audience, key message, tone, channels |
+| `digital-ads.md` | Google Ads + Meta/Instagram + TikTok (all formats and A/B variants) |
+| `email-sequences.md` | All sequences with subject lines, body copy, CTAs |
+| `landing-page.md` | Full page structure with above-fold and sections |
+| `social-media.md` | Per-platform posts with copy, visual direction, hashtags |
+| `sales-content.md` | Sales enablement + content marketing combined |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### campaign-strategy.md
+- **Objective:** campaign goal
+- **Target audience:** segments
+- **Key message:** core message
+- **Tone:** voice and tone for campaign
+- **Channels:** distribution strategy
+
+### digital-ads.md
+- **Google Ads:** Format, Headline, Description, CTA, Visual Direction
+- **Meta / Instagram:** Format, Copy, Visual Direction, CTA, A/B Variant
+- **TikTok:** Format, Hook, Copy, Visual Direction
+
+### email-sequences.md
+- **Welcome series:** 3 emails with subject, purpose, body copy, CTA
+- **Promotional:** email specs
+- **Re-engagement:** email specs
+
+### landing-page.md
+- **Headline:** main headline
+- **Subhead:** supporting copy
+- **Hero:** visual direction
+- **CTA:** primary call to action
+- **Social proof:** approach
+- Full section-by-section page structure
+
+### social-media.md
+- Per-platform table: Platform, Post Type, Copy, Visual Direction, Hashtags
+
+### sales-content.md
+- **Sales enablement:** materials list with descriptions
+- **Content marketing:** content pieces with topics and formats

package/templates/phases/research.md

@@ -1,53 +1,81 @@
-# Design Trends Report
+# Project Research
 
 ## Project: {PROJECT_NAME}
-**Industry:** {INDUSTRY}
+**Brand:** {BRAND_NAME}
 **Date:** {DATE}
 
 ---
 
-## Macro Trends
-
-### Trend 1: {TREND_NAME}
-- **Definition:** {DEFINITION}
-- **Visual language:** {VISUAL_DESCRIPTION}
-- **Adoption phase:** {EARLY/GROWTH/MATURE}
-- **Brand examples:** {BRAND_1}, {BRAND_2}, {BRAND_3}
-- **Opportunities:** {OPPORTUNITIES}
-- **Risks:** {RISKS}
-
-<!-- Repeat for 5 trends -->
-
-## Competitor Map
-
-### 2x2 Positioning
-```
-         Conservative ←→ Progressive
-Traditional
-     ↕        [Competitor positions]
-Modern
-```
-
-### White Space Insights
-- {INSIGHT_1}
-- {INSIGHT_2}
-
-## User Expectation Shifts
-- {SHIFT_1}
-- {SHIFT_2}
-
-## Platform Evolution
-- **iOS:** {IOS_TRENDS}
-- **Material Design:** {MATERIAL_TRENDS}
-- **Web:** {WEB_TRENDS}
-
-## Strategic Recommendations
-1. {RECOMMENDATION_1}
-2. {RECOMMENDATION_2}
-3. {RECOMMENDATION_3}
-
-## Mood Board Direction
-- **Palette:** {COLORS}
-- **Typography:** {TYPE_DIRECTION}
-- **Imagery:** {IMAGERY_STYLE}
-- **Texture/Pattern:** {TEXTURE}
+> This phase produces deep research chunks + INDEX.md in the `research/` directory. Research is project-specific — focused on UX patterns, competitor experiences, technical approaches, and accessibility strategies for what this project is building.
+
+## Chunk Mapping
+
+### Research Chunks (`research/`)
+
+| Chunk File | Content |
+|-----------|---------|
+| `ux-patterns.md` | UX patterns and best practices for this product type |
+| `competitor-ux.md` | Competitor UX analysis — how others solve similar problems |
+| `technical-research.md` | Technical approach research — framework patterns, architecture decisions, integration strategies |
+| `accessibility-patterns.md` | Accessibility patterns and strategies specific to this product type |
+| `content-strategy.md` | Content patterns, microcopy conventions, information density for this product type |
+| `reference-specs.md` | Collected specs, docs, and implementation references for execution |
+| `recommendations.md` | Synthesized recommendations — what to adopt, adapt, or avoid |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### ux-patterns.md
+- **Product type patterns:** established UX patterns for this category (e.g., dashboard, e-commerce, social, SaaS)
+- **Navigation patterns:** proven navigation approaches for this use case
+- **Interaction patterns:** common interaction models, gestures, affordances
+- **Information architecture:** how similar products organize content
+- **Onboarding patterns:** first-run experience approaches
+- **Empty state patterns:** how to handle no-content states
+- Sources and examples for each pattern
+
+### competitor-ux.md
+- **Competitor audit:** 3-5 competitor products analyzed
+- Per competitor: product, strengths, weaknesses, unique patterns, screenshots/descriptions
+- **Pattern comparison matrix:** feature × competitor showing approach differences
+- **Opportunity gaps:** things competitors do poorly or don't do at all
+- **Best-in-class examples:** specific UX moments worth studying
+
+### technical-research.md
+- **Framework patterns:** relevant patterns for the tech stack (React patterns, RN patterns, etc.)
+- **Component architecture:** proven component composition approaches for this product type
+- **State management:** recommended patterns for the complexity level
+- **Performance considerations:** lazy loading, virtualization, caching strategies
+- **Animation patterns:** motion design approaches appropriate for the platform
+- **Integration patterns:** API consumption, real-time data, offline support
+
+### accessibility-patterns.md
+- **Product-specific a11y:** accessibility considerations unique to this product type
+- **Keyboard navigation map:** how keyboard users should navigate this type of product
+- **Screen reader flow:** optimal reading order and announcements
+- **Focus management:** complex focus patterns (modals, drawers, dynamic content)
+- **Touch accessibility:** mobile-specific considerations
+- **Cognitive load:** reducing complexity for users with cognitive disabilities
+
+### content-strategy.md
+- **Microcopy conventions:** button labels, error messages, empty states, tooltips for this product type
+- **Information density:** appropriate content density per screen type
+- **Terminology:** domain-specific language considerations
+- **Tone adaptation:** how brand voice adapts to different UI contexts (errors, success, onboarding)
+
+### reference-specs.md
+- **API specs:** relevant API documentation, endpoints, data shapes for integrations
+- **Component library docs:** framework-specific component API references (shadcn docs, RN Reusables docs, etc.)
+- **Design token specs:** relevant token format specs, CSS custom property references
+- **Platform guidelines:** Apple HIG sections, Material Design sections, or platform-specific docs relevant to this project
+- **Accessibility specs:** WCAG criteria most relevant to this product type, with implementation guidance
+- **Third-party docs:** documentation for any third-party services, SDKs, or libraries the project will use
+- Each reference should include: source URL, key takeaways, how it applies to this project
+
+### recommendations.md
+- **Adopt:** patterns to use directly (with sources)
+- **Adapt:** patterns to modify for this project's needs
+- **Avoid:** anti-patterns and common mistakes for this product type
+- **Key decisions:** recommended approach for major UX decisions
+- Links to specific patterns in other research chunks