get-shit-pretty 0.2.0 → 0.4.0

package/templates/phases/review.md

@@ -1,88 +1,40 @@
-# Design Review
+# Deliverable Review
 
 ## Project: {PROJECT_NAME}
 **Date:** {DATE}
-**Reviewer:** GSP Design Critic + Accessibility Auditor
+**Reviewer:** GSP Deliverable Reviewer
 
 ---
 
-## Design Critique
+> This phase validates built deliverables against design intent. Produces acceptance chunks + INDEX.md in the `review/` directory.
 
-### Nielsen's Heuristics Evaluation
+## Chunk Mapping
 
-| # | Heuristic | Score (1-5) | Notes |
-|---|-----------|-------------|-------|
-| 1 | Visibility of system status | | |
-| 2 | Match between system and real world | | |
-| 3 | User control and freedom | | |
-| 4 | Consistency and standards | | |
-| 5 | Error prevention | | |
-| 6 | Recognition rather than recall | | |
-| 7 | Flexibility and efficiency of use | | |
-| 8 | Aesthetic and minimalist design | | |
-| 9 | Help users recover from errors | | |
-| 10 | Help and documentation | | |
+### Review Chunks (`review/`)
 
-**Overall Score:** {SCORE}/50
+| Chunk File | Content |
+|-----------|---------|
+| `acceptance-report.md` | Overall pass/fail, implementation checklist, token audit, screen coverage |
+| `issues.md` | Issues found — deviations from design, missing implementations, token violations |
 
-### Visual Hierarchy
-{ASSESSMENT}
+## Content Reference
 
-### Typography & Color
-{ASSESSMENT}
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
 
-### Usability
-{ASSESSMENT}
+### acceptance-report.md
+- **Overall verdict:** Pass / Conditional Pass / Fail
+- **Implementation checklist:** per-screen implementation status (complete, partial, missing)
+- **Token audit:** design token usage compliance (correct tokens used, magic numbers found, missing tokens)
+- **Screen coverage:** designed screens vs built screens
+- **Component coverage:** designed components vs implemented components
+- **Accessibility compliance:** WCAG 2.2 AA checks on built code (contrast, ARIA, keyboard, focus)
+- **Responsive verification:** breakpoint behavior matches design intent
 
-### Prioritized Fixes
-
-#### Critical (Must Fix)
-1. {FIX}
-
-#### Important (High Priority)
-1. {FIX}
-
-#### Polish (If Time Allows)
-1. {FIX}
-
-### Alternative Directions
-1. **{DIRECTION_1}:** {DESCRIPTION}
-2. **{DIRECTION_2}:** {DESCRIPTION}
-
----
-
-## Accessibility Audit (WCAG 2.2 AA)
-
-### Perceivable
-- [ ] Alt text for images
-- [ ] Captions for media
-- [ ] Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text)
-- [ ] Text resizable to 200%
-
-### Operable
-- [ ] Full keyboard access
-- [ ] Visible focus indicators
-- [ ] Skip navigation
-- [ ] No motion triggers without alternative
-
-### Understandable
-- [ ] Language declared
-- [ ] Clear error messages
-- [ ] Contextual help available
-
-### Robust
-- [ ] Valid markup
-- [ ] ARIA roles used correctly
-
-### Mobile
-- [ ] Orientation support
-- [ ] Touch targets ≥ 44x44pt
-- [ ] Reachable UI elements
-
-### Violations Found
-| # | Issue | Severity | WCAG Criterion | Remediation |
-|---|-------|----------|----------------|-------------|
-| | | | | |
-
-### Accessibility Statement
-{STATEMENT}
+### issues.md
+- Issues table: Issue, Severity (Critical/Major/Minor), Screen/Component, Expected, Actual, Remediation
+- **Critical:** blocks acceptance — must fix before shipping
+- **Major:** significant deviation from design intent
+- **Minor:** polish items, minor inconsistencies
+- Links to design chunks: `../design/screen-{NN}-{name}.md`
+- Links to build output: `../build/components/{name}`
+- Links to brand system: `{BRAND_PATH}/system/components/{name}.md`

package/templates/phases/strategy.md

@@ -0,0 +1,67 @@
+# Brand Strategy
+
+## Brand: {BRAND_NAME}
+**Date:** {DATE}
+
+---
+
+> This phase produces 6 chunks + INDEX.md in the `strategy/` directory.
+
+## Inputs
+- BRIEF.md
+- discover/competitive-audit.md → positioning.md, brand-prism.md
+- discover/audience-personas.md → brand-prism.md (Reflection, Self-Image)
+- discover/swot-analysis.md → brand-platform.md
+- discover/trend-analysis.md → archetype.md (avoid saturated archetypes)
+- discover/mood-board-direction.md → brand-prism.md (Physique)
+- discover/strategic-recommendations.md → brand-platform.md
+- audit/evolution-map.md (if exists) → evaluate current vs proposed
+
+## Chunk Mapping
+
+| Chunk File | Content |
+|-----------|---------|
+| `brand-prism.md` | Kapferer's 6 facets |
+| `archetype.md` | Primary + secondary Jungian archetypes |
+| `golden-circle.md` | Why / How / What |
+| `positioning.md` | Positioning statement + competitive map |
+| `brand-platform.md` | Purpose, Vision, Mission, Values, Promise |
+| `messaging-hierarchy.md` | Core message, supporting messages, elevator pitch |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### brand-prism.md
+- **Physique** — tangible, physical qualities
+- **Personality** — brand's character as a person
+- **Culture** — values and principles
+- **Relationship** — how brand relates to audience
+- **Reflection** — how audience sees themselves through brand
+- **Self-Image** — how audience feels using the brand
+
+### archetype.md
+- Primary archetype + secondary influence
+- Rationale for selection
+- Strengths and shadow traits to avoid
+- Communication style
+- Visual tendencies
+
+### golden-circle.md
+- **Why** — purpose beyond profit
+- **How** — process to deliver on purpose
+- **What** — products/services offered
+
+### positioning.md
+- Positioning statement: For {audience} who {need}, {brand} is the {category} that {benefit} because {reason}
+- 2-axis positioning map with competitors plotted
+- White space analysis
+
+### brand-platform.md
+- Purpose, Vision, Mission, Values, Promise
+- Each specific and ownable
+
+### messaging-hierarchy.md
+- Core message
+- 3 supporting messages with proof points
+- Elevator pitch (30 seconds)

package/templates/phases/system.md

@@ -1,84 +1,90 @@
 # Design System
 
-## Project: {PROJECT_NAME}
+## Brand: {BRAND_NAME}
 **Date:** {DATE}
 
+> Created once per brand. Reused across all projects.
+
 ---
 
-## Foundations
-
-### Color System
-<!-- Full color palette with semantic mapping -->
-
-### Typography Scale
-| Level | Size | Weight | Line Height | Use |
-|-------|------|--------|-------------|-----|
-| Display | | | | |
-| H1 | | | | |
-| H2 | | | | |
-| H3 | | | | |
-| Body Large | | | | |
-| Body | | | | |
-| Body Small | | | | |
-| Caption | | | | |
-| Overline | | | | |
-
-### Grid System
-- **Columns:** 12
-- **Gutter:** {GUTTER}px
-- **Margin:** {MARGIN}px
-- **Breakpoints:** {BREAKPOINTS}
-
-### Spacing Scale
-- **Base unit:** 8px
-- **Scale:** 4, 8, 12, 16, 24, 32, 48, 64, 96
-
-### Elevation / Shadow
-| Level | Use | Value |
-|-------|-----|-------|
-| 0 | Flat | none |
-| 1 | Cards | |
-| 2 | Dropdowns | |
-| 3 | Modals | |
-| 4 | Popovers | |
-
-### Border Radius
-| Token | Value | Use |
-|-------|-------|-----|
-| none | 0 | |
-| sm | | |
-| md | | |
-| lg | | |
-| full | 9999px | Pills, avatars |
-
-## Components
-
-### Buttons
-<!-- States: default, hover, active, disabled, loading -->
-
-### Inputs
-<!-- States: default, focus, error, disabled, filled -->
-
-### Cards
-<!-- Variants and anatomy -->
-
-### Navigation
-<!-- Patterns and responsive behavior -->
-
-### Modals / Dialogs
-<!-- Structure and behavior -->
-
-<!-- Continue for 30+ components -->
-
-## Design Tokens
-See `tokens.json` for machine-readable token export.
-
-## Principles
-1. {PRINCIPLE_1}
-2. {PRINCIPLE_2}
-3. {PRINCIPLE_3}
-
-## Do's and Don'ts
-| Do | Don't |
-|----|-------|
-| | |
+> This phase produces foundation chunks in `system/foundations/`, component chunks in `system/components/`, plus `principles.md`, `tokens.json`, and `INDEX.md`.
+
+## Inputs
+- identity/color-system.md → foundations/color-system.md
+- identity/palettes.json → token generation
+- identity/typography.md → foundations/typography.md
+- identity/logo-directions.md → clear space tokens
+- strategy/archetype.md + strategy/brand-platform.md → principles.md
+- verbal/brand-voice.md → content component guidelines
+- config.json system_config — tech_stack, system_strategy
+
+## Chunk Mapping
+
+### Foundations (`system/foundations/`)
+
+| Chunk File | Content |
+|-----------|---------|
+| `foundations/color-system.md` | Primary, secondary, semantic, neutral scale, dark mode, contrast ratios |
+| `foundations/typography.md` | 9-level type scale (Display → Overline) with all properties |
+| `foundations/spacing.md` | 8px base unit spacing scale |
+| `foundations/grid.md` | 12-column grid with gutters, margins, breakpoints |
+| `foundations/elevation.md` | 5 shadow levels with use cases and values |
+| `foundations/border-radius.md` | Token scale (none, sm, md, lg, xl, full) |
+
+### Components (`system/components/`)
+
+One chunk per component (`{name}.md`), singular kebab-case naming.
+Each includes: states, anatomy, usage rules, accessibility spec, code hints.
+
+### Other Files
+
+| File | Content |
+|-----------|---------|
+| `principles.md` | 3-5 design principles + do's and don'ts |
+| `tokens.json` | Complete W3C Design Tokens format (color, typography, spacing, shadow, border-radius, breakpoints) |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### foundations/color-system.md
+- Full color palette with semantic mapping
+- Primary, secondary, accent, background, text colors
+- Semantic colors: error, success, warning, info
+- Neutral scale
+- Dark mode mapping
+- Contrast ratios (WCAG AA)
+
+### foundations/typography.md
+- Type scale table: Level, Size, Weight, Line Height, Letter Spacing, Use
+- Levels: Display, H1, H2, H3, Body Large, Body, Body Small, Caption, Overline
+
+### foundations/spacing.md
+- Base unit: 8px
+- Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96
+- Usage guidelines per scale value
+
+### foundations/grid.md
+- Columns: 12
+- Gutter, margin values
+- Breakpoint definitions and behavior
+
+### foundations/elevation.md
+- 5 levels (0–4): Flat, Cards, Dropdowns, Modals, Popovers
+- CSS shadow values per level
+
+### foundations/border-radius.md
+- Token scale: none (0), sm, md, lg, xl, full (9999px)
+- Use cases per token
+
+### Component chunks
+- States: default, hover, active, disabled, focus, loading
+- Anatomy diagram
+- Usage rules
+- Accessibility spec
+- Code hints
+- Cross-references to foundation chunks
+
+### principles.md
+- 3-5 design principles with rationale
+- Do's and Don'ts table

package/templates/phases/verbal.md

@@ -0,0 +1,63 @@
+# Verbal Identity
+
+## Brand: {BRAND_NAME}
+**Date:** {DATE}
+
+---
+
+> This phase produces 7 chunks + INDEX.md in the `verbal/` directory.
+
+## Inputs
+- BRIEF.md — audience context
+- strategy/brand-prism.md Personality → brand-voice.md
+- strategy/archetype.md communication style → tone-spectrum.md
+- strategy/brand-platform.md Purpose/Vision → brand-narrative.md
+- strategy/brand-platform.md Promise → tagline-directions.md
+- strategy/messaging-hierarchy.md + discover/audience-personas.md → messaging-matrix.md
+- audit/brand-inventory.md voice samples (if exists) → baseline for voice evolution
+
+## Chunk Mapping
+
+| Chunk File | Content |
+|-----------|---------|
+| `brand-voice.md` | 3-5 voice attributes with means/doesn't mean |
+| `tone-spectrum.md` | 5 scales with default position + context shifts |
+| `voice-chart.md` | Do/Don't per attribute + grammar/style rules |
+| `messaging-matrix.md` | Messages by audience segment |
+| `brand-narrative.md` | Origin story + 4-part story arc |
+| `tagline-directions.md` | 3 distinct tagline directions |
+| `nomenclature.md` | Naming conventions, principles, terminology |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### brand-voice.md
+- 3-5 voice attributes table: Attribute, Description, Example
+- Voice personality description
+- Each attribute has "means / doesn't mean" + concrete examples
+
+### tone-spectrum.md
+- 5 scales (Formal↔Casual, Serious↔Playful, Authoritative↔Friendly, Technical↔Simple, Reserved↔Enthusiastic) with brand position
+- Tone by context table: Context, Tone Shift, Example (8-10 contexts)
+
+### voice-chart.md
+- Do/Don't per attribute with real writing examples
+- Before/after examples
+- Grammar and style rules (contractions, emoji, exclamation marks)
+
+### messaging-matrix.md
+- Table: Audience, Key Message, Tone, Proof Point, Channel
+- At least 3 audience segments
+
+### brand-narrative.md
+- Origin story
+- 4-part story arc: Setup → Tension → Resolution → Transformation
+
+### tagline-directions.md
+- 3 directions each with: tagline, approach/rationale, best-use context
+
+### nomenclature.md
+- Naming conventions: Products, Features, Plans/tiers, Internal tools
+- 3 naming principles
+- Terminology guide: Use / Don't Use / Reason

package/templates/{project.md → projects/brief.md}

@@ -1,21 +1,19 @@
-# Design Brief
+# Project Brief
 
 ## Project
 - **Name:** {PROJECT_NAME}
 - **Type:** {PROJECT_TYPE}
 - **Date:** {DATE}
+- **Brand:** {BRAND_NAME}
 
-## Brand
-- **Company:** {COMPANY}
-- **Industry:** {INDUSTRY}
-- **Existing brand?** {YES_NO}
-- **Brand personality:** {PERSONALITY}
+## What We're Building
+- **Description:** {DESCRIPTION}
+- **Platforms:** {PLATFORMS}
+- **Key screens/flows:** {KEY_SCREENS}
 
 ## Audience
 - **Primary:** {PRIMARY_AUDIENCE}
 - **Secondary:** {SECONDARY_AUDIENCE}
-- **Demographics:** {DEMOGRAPHICS}
-- **Psychographics:** {PSYCHOGRAPHICS}
 
 ## Goals
 - **Business goal:** {BUSINESS_GOAL}
@@ -26,20 +24,18 @@
 - **Platform:** {PLATFORMS}
 - **Tech stack:** {TECH_STACK}
 - **Timeline:** {TIMELINE}
-- **Budget:** {BUDGET}
 - **Accessibility:** WCAG 2.2 AA (default)
 
-## Inspiration
-- **Brands admired:** {BRANDS}
-- **Styles liked:** {STYLES}
-- **Styles to avoid:** {AVOID}
+## Scope
+- **Design scope:** {full | partial | tokens}
+- **Target screens:** {ALL or list of specific screens/flows}
+- **Codebase type:** {greenfield | boilerplate | existing}
+- **Implementation target:** {code | shadcn | rn-reusables | existing | figma | skip}
 
 ## Deliverables
-- [ ] Research & trends
-- [ ] Brand identity
-- [ ] Design system
+- [ ] Design system + tokens
 - [ ] UI/UX screens
-- [ ] Figma specs
+- [ ] Implementation specs
 - [ ] Design review
 - [ ] Code components
 - [ ] Marketing assets

package/templates/projects/config.json

@@ -0,0 +1,32 @@
+{
+  "version": "0.4.0",
+  "project_type": "design",
+  "project": {
+    "name": "",
+    "type": "",
+    "created": ""
+  },
+  "brand_ref": "",
+  "preferences": {
+    "platform": "web",
+    "tech_stack": "React + Tailwind",
+    "accessibility_level": "WCAG 2.2 AA",
+    "design_tool": "Figma",
+    "implementation_target": "code",
+    "codebase_type": "greenfield",
+    "design_scope": "full"
+  },
+  "git": {
+    "branch": "",
+    "pr": "",
+    "issues": []
+  },
+  "phases": {
+    "brief": { "status": "pending", "output": "brief/" },
+    "research": { "status": "pending", "output": "research/" },
+    "design": { "status": "pending", "output": "design/" },
+    "critique": { "status": "pending", "output": "critique/" },
+    "build": { "status": "pending", "output": "build/" },
+    "review": { "status": "pending", "output": "review/" }
+  }
+}

package/templates/projects/roadmap.md

@@ -0,0 +1,59 @@
+# Project Roadmap
+
+## Project: {PROJECT_NAME}
+**Brand:** {BRAND_NAME}
+**Created:** {DATE}
+
+> Treat this project as a bounded issue (or set of issues) and a PR. Ship small, ship complete.
+
+---
+
+## Phase 1: Brief
+**Status:** pending
+**Command:** `/gsp:brief`
+**Input:** Brand system + BRIEF.md
+**Output:** `brief/` (scope, adaptations, conditionals)
+**Goal:** Scope the project — screen list, priorities, component adaptations, gap analysis.
+
+## Phase 2: Research
+**Status:** pending
+**Command:** `/gsp:research`
+**Input:** Brief scope + brand system + BRIEF.md
+**Output:** `research/` (UX patterns, competitor UX, technical research, accessibility patterns)
+**Goal:** Deep project-level research — UX patterns, competitor analysis, technical approaches, accessibility strategies.
+
+## Phase 3: Design
+**Status:** pending
+**Command:** `/gsp:design`
+**Input:** Research + brief + brand system + BRIEF.md
+**Output:** `design/` (screen chunks + shared/)
+**Goal:** Design core screens, flows, and interaction patterns.
+
+## Phase 4: Critique
+**Status:** pending
+**Command:** `/gsp:critique`
+**Input:** All prior artifacts
+**Output:** `critique/` (critique + accessibility chunks)
+**Goal:** Critique design quality and audit accessibility compliance.
+
+## Phase 5: Build
+**Status:** pending
+**Command:** `/gsp:build`
+**Input:** Design + brief + brand system
+**Output:** `build/CODE.md` + `build/components/`
+**Goal:** Translate design into production-ready frontend code.
+
+## Phase 6: Review
+**Status:** pending
+**Command:** `/gsp:review`
+**Input:** Built deliverables + design intent
+**Output:** `review/` (acceptance report + issues)
+**Goal:** Validate built deliverables against design intent — token compliance, screen coverage, accessibility.
+
+---
+
+## Optional: Launch
+**Command:** `/gsp:launch`
+**Input:** Brand identity + verbal + design
+**Output:** `launch/` (campaign chunks)
+**Goal:** Create marketing campaign assets for launch. Run when needed.

package/templates/{state.md → projects/state.md}

@@ -1,6 +1,7 @@
 # Design State
 
 ## Project: {PROJECT_NAME}
+**Brand:** {BRAND_NAME}
 **Started:** {DATE}
 **Current Phase:** 0 (Not started)
 **Prettiness Level:** 0%
@@ -11,24 +12,33 @@
 
 | # | Phase | Status | Started | Completed |
 |---|-------|--------|---------|-----------|
-| 1 | Research | pending | — | — |
-| 2 | Brand | pending | — | — |
-| 3 | System | pending | — | — |
-| 4 | Design | pending | — | — |
-| 5 | Spec | pending/skipped | — | — |
+| 1 | Brief | pending | — | — |
+| 2 | Research | pending | — | — |
+| 3 | Design | pending | — | — |
+| 4 | Critique | pending | — | — |
+| 5 | Build | pending | — | — |
 | 6 | Review | pending | — | — |
-| 7 | Build | pending | — | — |
-| 8 | Launch | pending | — | — |
+
+## Git
+
+| Field | Value |
+|-------|-------|
+| Branch | — |
+| PR | — |
+| Issues | — |
 
 ## Review Loops
-<!-- Track review → fix → re-review cycles -->
+<!-- Track critique → fix → re-critique cycles -->
 
 | Loop | Date | Issues Found | Issues Fixed | Resubmitted |
 |------|------|-------------|-------------|-------------|
 
 ## Status Values
 <!-- pending | in-progress | complete | needs-revision | skipped -->
-<!-- Skipped phases count as complete for prettiness calculation -->
+
+## Launch
+<!-- Optional — run /gsp:launch when needed -->
+<!-- Status: not started -->
 
 ## Decisions
 <!-- Key design decisions and rationale -->